Projects · djuleayo

Projects · djuleayo https://c46f8f3d.personalpage-ahl.pages.dev/projects/ Things I build, and the ideas behind them. Hugo en Trust Based Auth https://c46f8f3d.personalpage-ahl.pages.dev/projects/trust-based-auth/ https://c46f8f3d.personalpage-ahl.pages.dev/projects/trust-based-auth/ Tue, 03 Nov 2026 00:00:00 UTC Trust based auth removes sign-up, passwords, and repeat verification. Successful interactions earn direct access. Telephony connects calls to web intent, and SMS activates a remembered browser session. Returning users act directly while the server checks current permission. <figure class="project-diagram" aria-labelledby="trust-journey-caption"> <div class="project-diagram-body"> First interaction Establish trust and a browser session <ol class="project-flow project-flow-four"> <li>Start in the appIntent saved, no sign-up</li> <li>Confirm by phoneCall linked to web intent</li> <li class="flow-positive">Earn trustSuccessful fulfillment confirmed</li> <li>Activate browserSMS code establishes session</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Return visits Less work for the user; permission still checked <ol class="project-flow project-flow-three"> <li>ReturnBrowser remembers the session</li> <li>Check permissionServer checks current trust</li> <li class="flow-positive">Act directlyNo repeat call or SMS code</li> </ol> </div> <figcaption id="trust-journey-caption">Earned trust removes repeat steps while an active session and current permission allow direct access.</figcaption> </figure> <h2 id="friction-removal-by-design"> Friction removal by design <a class="heading-link" href="#friction-removal-by-design"> Link to heading </a> </h2> The app lets people express intent before asking them to establish an identity. Their work is already captured when the first call confirms the interaction, and successful fulfillment earns a shorter path next time. Trust carries forward across visits. SMS activation establishes the browser session; it does not interrupt every subsequent action. A new browser or an expired session needs activation again. <h2 id="telephony-integration"> Telephony integration <a class="heading-link" href="#telephony-integration"> Link to heading </a> </h2> The phone call arrives with context. An Asterisk/GSM gateway sends call events to the web application, where the caller&rsquo;s phone number is connected to saved intent. An operator can see what the person has already selected. If there are multiple candidate carts, a short cart code resolves the match. <figure class="project-diagram" aria-labelledby="telephony-integration-caption"> <div class="project-diagram-body"> Inbound call Bring the user's web context into the conversation <ol class="project-flow project-flow-three"> <li>User callsFrom their phone</li> <li>Asterisk/GSM gatewayAuthenticated call webhook</li> <li class="flow-positive">Web applicationMatch caller to saved intent</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Outbound SMS Connect the phone to a remembered browser session <ol class="project-flow project-flow-three"> <li>Web applicationQueue activation code</li> <li>GSM gatewayDeliver SMS</li> <li class="flow-positive">User's phoneCode activates browser session</li> </ol> </div> <figcaption id="telephony-integration-caption">Calls carry context into the app; SMS connects the user back to it.</figcaption> </figure> The same integration carries SMS activation back to the user&rsquo;s phone. Calls, saved web intent, and session activation become parts of one flow, reducing repeated explanations and data entry. <h2 id="trust-follows-outcomes"> Trust follows outcomes <a class="heading-link" href="#trust-follows-outcomes"> Link to heading </a> </h2> Fulfilled commitments unlock direct access. Recorded no-shows restrict it. An operator confirms the outcome; the server updates the user&rsquo;s trust state. <figure class="project-diagram" aria-labelledby="trust-outcomes-caption"> <div class="project-diagram-body"> Trust updates Real outcomes determine permission <div class="trust-root">Operator confirms the outcome</div> <div class="trust-branches"> <div class="trust-branch"> Fulfillment confirmed <div class="trust-result flow-positive"> TRUSTED Direct access allowed </div> </div> <div class="trust-branch"> No-show recorded <div class="trust-result flow-restricted"> NOT_TRUSTED Direct checkout blocked </div> </div> </div> Every direct checkout checks the current trust state and the phone-linked session. </div> <figcaption id="trust-outcomes-caption">Operator-confirmed outcomes update trust. An existing browser session cannot bypass the permission check.</figcaption> </figure> New phone numbers start as <code>UNKNOWN</code>. A confirmed fulfillment changes the user to <code>TRUSTED</code>; a recorded no-show changes them to <code>NOT_TRUSTED</code>. The current implementation uses completed orders as the evidence for these decisions. The model also supports <code>MEDIUM</code>, which permits direct orders with the possibility of operator review. The outcome handler currently assigns the trusted and restricted states; it does not automatically assign this intermediate state. <h2 id="keep-permission-current"> Keep permission current <a class="heading-link" href="#keep-permission-current"> Link to heading </a> </h2> A remembered browser still needs current permission. SMS activation establishes access to a phone-linked session. The outcome history determines whether that user is eligible to act directly. At every direct checkout, the server checks session validity, the matching phone number, and the user&rsquo;s current trust state. A restriction takes effect even if the browser still has a valid session. Session tokens are hashed on the server and carried in an HttpOnly cookie. Activation codes expire and have limited attempts. Trust changes record the previous state, new state, related order, and responsible operator. <h2 id="implementation"> Implementation <a class="heading-link" href="#implementation"> Link to heading </a> </h2> Built with Next.js, TypeScript, Prisma, and SQLite, with Asterisk/GSM for calls and SMS. The operator workspace brings call context, saved carts, fulfillment, and trust decisions together. Trust based auth removes sign-up, passwords, and repeat verification. Successful interactions earn direct access. Telephony connects calls to web intent, and SMS activates a remembered browser session. Returning users act directly while the server checks current permission. <figure class="project-diagram" aria-labelledby="trust-journey-caption"> <div class="project-diagram-body"> First interaction Establish trust and a browser session <ol class="project-flow project-flow-four"> <li>Start in the appIntent saved, no sign-up</li> <li>Confirm by phoneCall linked to web intent</li> <li class="flow-positive">Earn trustSuccessful fulfillment confirmed</li> <li>Activate browserSMS code establishes session</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Return visits Less work for the user; permission still checked <ol class="project-flow project-flow-three"> <li>ReturnBrowser remembers the session</li> <li>Check permissionServer checks current trust</li> <li class="flow-positive">Act directlyNo repeat call or SMS code</li> </ol> </div> <figcaption id="trust-journey-caption">Earned trust removes repeat steps while an active session and current permission allow direct access.</figcaption> </figure> <h2 id="friction-removal-by-design"> Friction removal by design <a class="heading-link" href="#friction-removal-by-design"> Link to heading </a> </h2> The app lets people express intent before asking them to establish an identity. Their work is already captured when the first call confirms the interaction, and successful fulfillment earns a shorter path next time. Trust carries forward across visits. SMS activation establishes the browser session; it does not interrupt every subsequent action. A new browser or an expired session needs activation again. <h2 id="telephony-integration"> Telephony integration <a class="heading-link" href="#telephony-integration"> Link to heading </a> </h2> The phone call arrives with context. An Asterisk/GSM gateway sends call events to the web application, where the caller&rsquo;s phone number is connected to saved intent. An operator can see what the person has already selected. If there are multiple candidate carts, a short cart code resolves the match. <figure class="project-diagram" aria-labelledby="telephony-integration-caption"> <div class="project-diagram-body"> Inbound call Bring the user's web context into the conversation <ol class="project-flow project-flow-three"> <li>User callsFrom their phone</li> <li>Asterisk/GSM gatewayAuthenticated call webhook</li> <li class="flow-positive">Web applicationMatch caller to saved intent</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Outbound SMS Connect the phone to a remembered browser session <ol class="project-flow project-flow-three"> <li>Web applicationQueue activation code</li> <li>GSM gatewayDeliver SMS</li> <li class="flow-positive">User's phoneCode activates browser session</li> </ol> </div> <figcaption id="telephony-integration-caption">Calls carry context into the app; SMS connects the user back to it.</figcaption> </figure> The same integration carries SMS activation back to the user&rsquo;s phone. Calls, saved web intent, and session activation become parts of one flow, reducing repeated explanations and data entry. <h2 id="trust-follows-outcomes"> Trust follows outcomes <a class="heading-link" href="#trust-follows-outcomes"> Link to heading </a> </h2> Fulfilled commitments unlock direct access. Recorded no-shows restrict it. An operator confirms the outcome; the server updates the user&rsquo;s trust state. <figure class="project-diagram" aria-labelledby="trust-outcomes-caption"> <div class="project-diagram-body"> Trust updates Real outcomes determine permission <div class="trust-root">Operator confirms the outcome</div> <div class="trust-branches"> <div class="trust-branch"> Fulfillment confirmed <div class="trust-result flow-positive"> TRUSTED Direct access allowed </div> </div> <div class="trust-branch"> No-show recorded <div class="trust-result flow-restricted"> NOT_TRUSTED Direct checkout blocked </div> </div> </div> Every direct checkout checks the current trust state and the phone-linked session. </div> <figcaption id="trust-outcomes-caption">Operator-confirmed outcomes update trust. An existing browser session cannot bypass the permission check.</figcaption> </figure> New phone numbers start as <code>UNKNOWN</code>. A confirmed fulfillment changes the user to <code>TRUSTED</code>; a recorded no-show changes them to <code>NOT_TRUSTED</code>. The current implementation uses completed orders as the evidence for these decisions. The model also supports <code>MEDIUM</code>, which permits direct orders with the possibility of operator review. The outcome handler currently assigns the trusted and restricted states; it does not automatically assign this intermediate state. <h2 id="keep-permission-current"> Keep permission current <a class="heading-link" href="#keep-permission-current"> Link to heading </a> </h2> A remembered browser still needs current permission. SMS activation establishes access to a phone-linked session. The outcome history determines whether that user is eligible to act directly. At every direct checkout, the server checks session validity, the matching phone number, and the user&rsquo;s current trust state. A restriction takes effect even if the browser still has a valid session. Session tokens are hashed on the server and carried in an HttpOnly cookie. Activation codes expire and have limited attempts. Trust changes record the previous state, new state, related order, and responsible operator. <h2 id="implementation"> Implementation <a class="heading-link" href="#implementation"> Link to heading </a> </h2> Built with Next.js, TypeScript, Prisma, and SQLite, with Asterisk/GSM for calls and SMS. The operator workspace brings call context, saved carts, fulfillment, and trust decisions together. Agentic Voice System https://c46f8f3d.personalpage-ahl.pages.dev/projects/agentic-voice-agent/ https://c46f8f3d.personalpage-ahl.pages.dev/projects/agentic-voice-agent/ Tue, 03 Nov 2026 00:00:00 UTC LLM voice agents that handle real calls, use your business systems, and follow workflows you can test and control. Callers can ask questions, correct information, and interrupt. The system interprets their meaning, keeps accepted task state, and carries the work forward. <nav class="project-jumps" aria-label="Explore this project"> <a href="#a-call-that-stays-on-task">Call example</a> <a href="#write-the-workflow-with-ordinary-awaits">Authoring</a> <a href="#test-models-and-control-performance">Testing &amp; performance</a> <a href="#the-architecture-behind-the-behavior">Architecture</a> <a href="#telephony-and-infrastructure">Infrastructure</a> <a href="#rsi-trace-driven-improvement">RSI loop</a> </nav> <h2 id="a-call-that-stays-on-task"> A call that stays on task <a class="heading-link" href="#a-call-that-stays-on-task"> Link to heading </a> </h2> <figure class="project-diagram voice-call" aria-labelledby="voice-agent-call-caption"> <div class="project-diagram-body"> A question becomes a detour, then the task continues Illustrative call and execution <ol class="call-steps" role="list"> <li> <div>AskThe agent requests the caller's first name.</div> <code>collectGivenName(...)</code> waits for an accepted answer. </li> <li> <div>ExplainCaller: “Why do you need my name?” The agent explains its declared purpose.</div> Navigation visits the explanation goal; collection stays pending. </li> <li> <div>ResumeThe caller supplies a name. The agent accepts the validated answer and continues the task.</div> The collector returns. The parent resumes and invokes <code>inform(...)</code>, which checks its remaining requirements. </li> </ol> </div> <figcaption id="voice-agent-call-caption">A child goal can handle several turns while the parent's await remains suspended.</figcaption> </figure> <h2 id="write-the-workflow-with-ordinary-awaits"> Write the workflow with ordinary awaits <a class="heading-link" href="#write-the-workflow-with-ordinary-awaits"> Link to heading </a> </h2> <code>defineGoal</code> realizes a controlled state machine through ordinary async functions. The runtime keeps a logical goal stack alongside the language&rsquo;s async call chain. Each registered goal invocation adds a frame: a child can handle several conversational turns while its parent waits at <code>await</code>. An accepted result lets the parent resume. Illustrative composition; goal definitions and business schemas are omitted: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">const handleCall = defineGoal(callDefinition, async (input, ctx) =&gt; { await greet(input.introduction, ctx); await introduce(input.introduction, ctx); if (!ctx.state.values.identity?.givenName) { await collectGivenName(input.collection, ctx); } await inform(input.account, ctx); return callEnd({ ending: &#34;achieved&#34; }, ctx); }); </code></pre></div>The interface uses control flow developers already know. Calls, <code>if</code>, loops, <code>try</code>/<code>catch</code>, and returns express the workflow; goal frames add input/output validation, requirements, cancellation, and traces. Using the language&rsquo;s existing constructs reduces onboarding and everyday authoring friction from learning a state library&rsquo;s separate vocabulary. The graph visualizes goals and recorded transitions. <h2 id="test-models-and-control-performance"> Test models and control performance <a class="heading-link" href="#test-models-and-control-performance"> Link to heading </a> </h2> Model adapters are replaceable; the workflow stays in application code. Goals, validation rules, and allowed transitions keep their contracts as models and decision formulations change. <ul> <li>Test the workflow: supply known decisions and values as fixtures, then check transitions, prerequisites, and interruption handling without live inference.</li> <li>Measure the model: run a fixed corpus of caller evidence and expected decisions through a candidate provider, retaining failures as well as successes.</li> <li>Control the trade-off: compare decision quality and request latency on the same cases before changing a binding. Phase boundaries help locate whether a regression came from routing, interpretation, extraction, or generation.</li> </ul> <aside class="voice-performance" aria-label="Archived navigation result"> 93.4%navigation accuracy One recorded example: H2O-Lightning 4B on previously observed synthetic navigation cases, October 2026. The corpus makes decision quality measurable as the setup changes. </aside> <h2 id="the-architecture-behind-the-behavior"> The architecture behind the behavior <a class="heading-link" href="#the-architecture-behind-the-behavior"> Link to heading </a> </h2> Meaning comes before flow control. “Why do you need my name?” calls for an explanation; “I won&rsquo;t give my name” calls for the declared refusal policy. Both mention the same field. Semantic interpretation establishes which behavior applies, and code controls the allowed transition. <figure class="project-diagram" aria-labelledby="voice-agent-phases-caption"> <div class="project-diagram-body"> Four phases Route · interpret · extract · respond <ol class="project-flow project-flow-four" role="list"> <li>NavigationChoose a permitted goal</li> <li>RegressionSelect a declared semantic case</li> <li>ReductionExtract a provisional value</li> <li>GenerationProduce a scoped reply</li> </ol> Code validates candidates and controls acceptance. Branches without data skip reduction; successful collection can skip generation. </div> <figcaption id="voice-agent-phases-caption">Four responsibilities, each with a limited output contract and invoked when needed.</figcaption> </figure> Navigation and regression can use specialised finite-choice decision models. This implementation supports a local H2O model and an OpenAI navigation binding; arbitrary extraction and new free-form replies use a generative LLM. Authored templates can be delivered directly. Prepared turns remain provisional until accepted; cancellation preserves the suspended task. Speech delivery is tracked separately, so an interrupted message remains pending and changed facts can invalidate stale speech. <h2 id="telephony-and-infrastructure"> Telephony and infrastructure <a class="heading-link" href="#telephony-and-infrastructure"> Link to heading </a> </h2> SIP telephony connects inbound and outbound calls to the agent. LiveKit carries the media; isolated call processes coordinate speech providers, decisions, and business services. PostgreSQL and MinIO retain history and traces, with a dashboard for live and recorded execution. <figure class="project-diagram voice-infrastructure" aria-labelledby="voice-agent-system-caption"> <div class="project-diagram-body"> Media path and call execution <ol class="project-flow project-flow-three project-flow-bidirectional" role="list"> <li>Phone networkInbound and outbound SIP / PBX</li> <li>LiveKit + SIP bridgeRooms, media, and Redis coordination</li> <li class="flow-positive">Call workerIsolated process for each admitted call</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Services around the worker <ul class="infra-services" role="list"> <li class="project-node">Speech providersRecognition and synthesis</li> <li class="project-node">Decision models + LLMLocal GPU gateway in dev; provider APIs</li> <li class="project-node">PostgreSQL + MinIOHistory, checkpoints, audio, and traces</li> <li class="project-node">OperationsNext.js dashboard; Prometheus / Grafana</li> </ul> </div> <figcaption id="voice-agent-system-caption">Two-way media connects the caller and agent; the worker uses models and business services and records execution.</figcaption> </figure> Docker deployments separate dev, stage, and production data while sharing telephony infrastructure. The development decision model can run behind an authenticated GPU gateway and SSH tunnel; Prometheus and Grafana provide host and container monitoring. <h2 id="rsi-trace-driven-improvement"> RSI: trace-driven improvement <a class="heading-link" href="#rsi-trace-driven-improvement"> Link to heading </a> </h2> RSI turns test calls into reviewable workflow improvements. A larger model exercises the agent, inspects the event trace and <code>defineGoal</code> code, and opens a merge request with a fix and a reproducing regression case. <figure class="project-diagram voice-rsi" aria-labelledby="voice-agent-rsi-caption"> <div class="project-diagram-body"> <ol class="project-flow project-flow-four" role="list"> <li class="flow-positive">Make test callsLarger model acts as caller and produces traces</li> <li>Inspect the traceLarger model diagnoses goals and transitions</li> <li>Open an MRFlow changes, trace evidence, and a regression case</li> <li>Retest the candidateCorpus, replay, and further model-driven calls</li> </ol> </div> <figcaption id="voice-agent-rsi-caption">Corpus and replay checks support review of the candidate. Further calls exercise the revised workflow and feed the next iteration.</figcaption> </figure> LLM voice agents that handle real calls, use your business systems, and follow workflows you can test and control. Callers can ask questions, correct information, and interrupt. The system interprets their meaning, keeps accepted task state, and carries the work forward. <nav class="project-jumps" aria-label="Explore this project"> <a href="#a-call-that-stays-on-task">Call example</a> <a href="#write-the-workflow-with-ordinary-awaits">Authoring</a> <a href="#test-models-and-control-performance">Testing &amp; performance</a> <a href="#the-architecture-behind-the-behavior">Architecture</a> <a href="#telephony-and-infrastructure">Infrastructure</a> <a href="#rsi-trace-driven-improvement">RSI loop</a> </nav> <h2 id="a-call-that-stays-on-task"> A call that stays on task <a class="heading-link" href="#a-call-that-stays-on-task"> Link to heading </a> </h2> <figure class="project-diagram voice-call" aria-labelledby="voice-agent-call-caption"> <div class="project-diagram-body"> A question becomes a detour, then the task continues Illustrative call and execution <ol class="call-steps" role="list"> <li> <div>AskThe agent requests the caller's first name.</div> <code>collectGivenName(...)</code> waits for an accepted answer. </li> <li> <div>ExplainCaller: “Why do you need my name?” The agent explains its declared purpose.</div> Navigation visits the explanation goal; collection stays pending. </li> <li> <div>ResumeThe caller supplies a name. The agent accepts the validated answer and continues the task.</div> The collector returns. The parent resumes and invokes <code>inform(...)</code>, which checks its remaining requirements. </li> </ol> </div> <figcaption id="voice-agent-call-caption">A child goal can handle several turns while the parent's await remains suspended.</figcaption> </figure> <h2 id="write-the-workflow-with-ordinary-awaits"> Write the workflow with ordinary awaits <a class="heading-link" href="#write-the-workflow-with-ordinary-awaits"> Link to heading </a> </h2> <code>defineGoal</code> realizes a controlled state machine through ordinary async functions. The runtime keeps a logical goal stack alongside the language&rsquo;s async call chain. Each registered goal invocation adds a frame: a child can handle several conversational turns while its parent waits at <code>await</code>. An accepted result lets the parent resume. Illustrative composition; goal definitions and business schemas are omitted: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">const handleCall = defineGoal(callDefinition, async (input, ctx) =&gt; { await greet(input.introduction, ctx); await introduce(input.introduction, ctx); if (!ctx.state.values.identity?.givenName) { await collectGivenName(input.collection, ctx); } await inform(input.account, ctx); return callEnd({ ending: &#34;achieved&#34; }, ctx); }); </code></pre></div>The interface uses control flow developers already know. Calls, <code>if</code>, loops, <code>try</code>/<code>catch</code>, and returns express the workflow; goal frames add input/output validation, requirements, cancellation, and traces. Using the language&rsquo;s existing constructs reduces onboarding and everyday authoring friction from learning a state library&rsquo;s separate vocabulary. The graph visualizes goals and recorded transitions. <h2 id="test-models-and-control-performance"> Test models and control performance <a class="heading-link" href="#test-models-and-control-performance"> Link to heading </a> </h2> Model adapters are replaceable; the workflow stays in application code. Goals, validation rules, and allowed transitions keep their contracts as models and decision formulations change. <ul> <li>Test the workflow: supply known decisions and values as fixtures, then check transitions, prerequisites, and interruption handling without live inference.</li> <li>Measure the model: run a fixed corpus of caller evidence and expected decisions through a candidate provider, retaining failures as well as successes.</li> <li>Control the trade-off: compare decision quality and request latency on the same cases before changing a binding. Phase boundaries help locate whether a regression came from routing, interpretation, extraction, or generation.</li> </ul> <aside class="voice-performance" aria-label="Archived navigation result"> 93.4%navigation accuracy One recorded example: H2O-Lightning 4B on previously observed synthetic navigation cases, October 2026. The corpus makes decision quality measurable as the setup changes. </aside> <h2 id="the-architecture-behind-the-behavior"> The architecture behind the behavior <a class="heading-link" href="#the-architecture-behind-the-behavior"> Link to heading </a> </h2> Meaning comes before flow control. “Why do you need my name?” calls for an explanation; “I won&rsquo;t give my name” calls for the declared refusal policy. Both mention the same field. Semantic interpretation establishes which behavior applies, and code controls the allowed transition. <figure class="project-diagram" aria-labelledby="voice-agent-phases-caption"> <div class="project-diagram-body"> Four phases Route · interpret · extract · respond <ol class="project-flow project-flow-four" role="list"> <li>NavigationChoose a permitted goal</li> <li>RegressionSelect a declared semantic case</li> <li>ReductionExtract a provisional value</li> <li>GenerationProduce a scoped reply</li> </ol> Code validates candidates and controls acceptance. Branches without data skip reduction; successful collection can skip generation. </div> <figcaption id="voice-agent-phases-caption">Four responsibilities, each with a limited output contract and invoked when needed.</figcaption> </figure> Navigation and regression can use specialised finite-choice decision models. This implementation supports a local H2O model and an OpenAI navigation binding; arbitrary extraction and new free-form replies use a generative LLM. Authored templates can be delivered directly. Prepared turns remain provisional until accepted; cancellation preserves the suspended task. Speech delivery is tracked separately, so an interrupted message remains pending and changed facts can invalidate stale speech. <h2 id="telephony-and-infrastructure"> Telephony and infrastructure <a class="heading-link" href="#telephony-and-infrastructure"> Link to heading </a> </h2> SIP telephony connects inbound and outbound calls to the agent. LiveKit carries the media; isolated call processes coordinate speech providers, decisions, and business services. PostgreSQL and MinIO retain history and traces, with a dashboard for live and recorded execution. <figure class="project-diagram voice-infrastructure" aria-labelledby="voice-agent-system-caption"> <div class="project-diagram-body"> Media path and call execution <ol class="project-flow project-flow-three project-flow-bidirectional" role="list"> <li>Phone networkInbound and outbound SIP / PBX</li> <li>LiveKit + SIP bridgeRooms, media, and Redis coordination</li> <li class="flow-positive">Call workerIsolated process for each admitted call</li> </ol> <div class="journey-divider" aria-hidden="true"></div> Services around the worker <ul class="infra-services" role="list"> <li class="project-node">Speech providersRecognition and synthesis</li> <li class="project-node">Decision models + LLMLocal GPU gateway in dev; provider APIs</li> <li class="project-node">PostgreSQL + MinIOHistory, checkpoints, audio, and traces</li> <li class="project-node">OperationsNext.js dashboard; Prometheus / Grafana</li> </ul> </div> <figcaption id="voice-agent-system-caption">Two-way media connects the caller and agent; the worker uses models and business services and records execution.</figcaption> </figure> Docker deployments separate dev, stage, and production data while sharing telephony infrastructure. The development decision model can run behind an authenticated GPU gateway and SSH tunnel; Prometheus and Grafana provide host and container monitoring. <h2 id="rsi-trace-driven-improvement"> RSI: trace-driven improvement <a class="heading-link" href="#rsi-trace-driven-improvement"> Link to heading </a> </h2> RSI turns test calls into reviewable workflow improvements. A larger model exercises the agent, inspects the event trace and <code>defineGoal</code> code, and opens a merge request with a fix and a reproducing regression case. <figure class="project-diagram voice-rsi" aria-labelledby="voice-agent-rsi-caption"> <div class="project-diagram-body"> <ol class="project-flow project-flow-four" role="list"> <li class="flow-positive">Make test callsLarger model acts as caller and produces traces</li> <li>Inspect the traceLarger model diagnoses goals and transitions</li> <li>Open an MRFlow changes, trace evidence, and a regression case</li> <li>Retest the candidateCorpus, replay, and further model-driven calls</li> </ol> </div> <figcaption id="voice-agent-rsi-caption">Corpus and replay checks support review of the candidate. Further calls exercise the revised workflow and feed the next iteration.</figcaption> </figure> Apispects https://c46f8f3d.personalpage-ahl.pages.dev/projects/apispects/ https://c46f8f3d.personalpage-ahl.pages.dev/projects/apispects/ Tue, 03 Nov 2026 00:00:00 UTC Reduce contract drift between backend and frontend with one shared API contract. Apispects derives an Express router and typed client from the same TypeScript declaration, including request schemas, success responses, and business errors. Teams get editor feedback as the interface changes, with fewer definitions and integration conventions to maintain separately. <figure class="project-diagram api-contract" aria-labelledby="apispects-contract-caption"> <div class="project-diagram-body"> One contract connects both sides Routes · Inputs · Responses · Business errors <div class="project-node flow-positive contract-source"> Shared TypeScript contract Zod schemas + <code>ApiSpec</code> </div> <ul class="contract-consumers" role="list"> <li class="project-node"> Backend Express router and typed handlers </li> <li class="project-node"> Frontend Typed calls, results, and business errors </li> </ul> </div> <figcaption id="apispects-contract-caption">Both interfaces derive from the same contract version. Teams keep ownership of their business logic and user experience.</figcaption> </figure> <h2 id="a-contribution-that-crosses-team-boundaries"> A contribution that crosses team boundaries <a class="heading-link" href="#a-contribution-that-crosses-team-boundaries"> Link to heading </a> </h2> Standardize the integration work teams repeat. Backend teams own handlers and business rules; frontend teams own the user experience. A shared contract gives both a consistent way to define endpoints, validate data, call services, and handle expected failures. A new endpoint follows the same path from declaration to handler to client call. Improvements to that path can benefit every team using it. Producers and consumers review changes against a common contract, reducing repeated decisions about payload shapes, endpoint wiring, and error formats. <h2 id="feedback-while-you-code"> Feedback while you code <a class="heading-link" href="#feedback-while-you-code"> Link to heading </a> </h2> The contract becomes the developer interface. Autocomplete exposes available operations, accepted inputs, returned data, and declared business errors. Type inference carries changes into controller arguments and client calls when consumers compile against the updated contract. <figure class="project-diagram api-editor-demo" aria-labelledby="apispects-demo-caption"> <a href="/tsapispec.demo.gif" aria-label="Open the TypeScript editor demo at full size"> <img src="/tsapispec.demo.gif" width="878" height="520" loading="lazy" decoding="async" alt="Editor demonstration of schema-driven autocomplete and type checking in a TypeScript controller."> </a> <figcaption id="apispects-demo-caption">Declared schemas supply controller types and immediate editor feedback. Open the recording to view it at full size.</figcaption> </figure> There is no separate client generation command or generated client file to refresh. TypeScript derives the interfaces; <code>makeApi</code> constructs the router and client functions from the declaration. <h2 id="define-once-use-on-both-sides"> Define once, use on both sides <a class="heading-link" href="#define-once-use-on-both-sides"> Link to heading </a> </h2> Illustrative composition; the shared contract, server setup, and client setup belong in separate modules. Imports and business logic are omitted. <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">// Shared contract const spec = { accounts: { create_post: { bodySchema: z.object({ name: z.string() }), responseSchema: z.object({ id: z.string() }), cbErrorSchema: z.literal(&#34;Name already taken&#34;), }, }, } as const satisfies ApiSpec; // Server: typed handler and Express router makeController(spec.accounts.create_post, createAccount); const { router } = makeApi(spec, {}, express.Router); // Client: typed calls and outcomes const { apiClient } = makeApi(spec, { baseUrl: apiOrigin }); const result = await apiClient.accounts.create_post({ body: { name: &#34;Ada&#34; }, }); </code></pre></div>Business errors belong to the contract too. The handler can return the declared <code>&quot;Name already taken&quot;</code> case. The client receives it through the common error envelope with its payload type preserved. Consumers can handle expected failures using the interface they already share with the backend. <h2 id="check-the-boundary-at-runtime"> Check the boundary at runtime <a class="heading-link" href="#check-the-boundary-at-runtime"> Link to heading </a> </h2> The server validates incoming request fields against their schemas. The client parses successful response data against the response schema; development mode also checks controller output before sending it. These checks complement the types used during development. Shared contract versions remain part of rollout coordination when clients and services deploy independently. The design reduces drift between maintained definitions and exposes incompatible data at the checked boundaries. Built with TypeScript, Zod, Express, and fetch. Explore the <a href="https://github.com/apispects/core" class="external-link" target="_blank" rel="noopener">source on GitHub</a> or the <a href="/posts/ts-api-spec/" >earlier TypeScript walkthrough</a>. Reduce contract drift between backend and frontend with one shared API contract. Apispects derives an Express router and typed client from the same TypeScript declaration, including request schemas, success responses, and business errors. Teams get editor feedback as the interface changes, with fewer definitions and integration conventions to maintain separately. <figure class="project-diagram api-contract" aria-labelledby="apispects-contract-caption"> <div class="project-diagram-body"> One contract connects both sides Routes · Inputs · Responses · Business errors <div class="project-node flow-positive contract-source"> Shared TypeScript contract Zod schemas + <code>ApiSpec</code> </div> <ul class="contract-consumers" role="list"> <li class="project-node"> Backend Express router and typed handlers </li> <li class="project-node"> Frontend Typed calls, results, and business errors </li> </ul> </div> <figcaption id="apispects-contract-caption">Both interfaces derive from the same contract version. Teams keep ownership of their business logic and user experience.</figcaption> </figure> <h2 id="a-contribution-that-crosses-team-boundaries"> A contribution that crosses team boundaries <a class="heading-link" href="#a-contribution-that-crosses-team-boundaries"> Link to heading </a> </h2> Standardize the integration work teams repeat. Backend teams own handlers and business rules; frontend teams own the user experience. A shared contract gives both a consistent way to define endpoints, validate data, call services, and handle expected failures. A new endpoint follows the same path from declaration to handler to client call. Improvements to that path can benefit every team using it. Producers and consumers review changes against a common contract, reducing repeated decisions about payload shapes, endpoint wiring, and error formats. <h2 id="feedback-while-you-code"> Feedback while you code <a class="heading-link" href="#feedback-while-you-code"> Link to heading </a> </h2> The contract becomes the developer interface. Autocomplete exposes available operations, accepted inputs, returned data, and declared business errors. Type inference carries changes into controller arguments and client calls when consumers compile against the updated contract. <figure class="project-diagram api-editor-demo" aria-labelledby="apispects-demo-caption"> <a href="/tsapispec.demo.gif" aria-label="Open the TypeScript editor demo at full size"> <img src="/tsapispec.demo.gif" width="878" height="520" loading="lazy" decoding="async" alt="Editor demonstration of schema-driven autocomplete and type checking in a TypeScript controller."> </a> <figcaption id="apispects-demo-caption">Declared schemas supply controller types and immediate editor feedback. Open the recording to view it at full size.</figcaption> </figure> There is no separate client generation command or generated client file to refresh. TypeScript derives the interfaces; <code>makeApi</code> constructs the router and client functions from the declaration. <h2 id="define-once-use-on-both-sides"> Define once, use on both sides <a class="heading-link" href="#define-once-use-on-both-sides"> Link to heading </a> </h2> Illustrative composition; the shared contract, server setup, and client setup belong in separate modules. Imports and business logic are omitted. <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">// Shared contract const spec = { accounts: { create_post: { bodySchema: z.object({ name: z.string() }), responseSchema: z.object({ id: z.string() }), cbErrorSchema: z.literal(&#34;Name already taken&#34;), }, }, } as const satisfies ApiSpec; // Server: typed handler and Express router makeController(spec.accounts.create_post, createAccount); const { router } = makeApi(spec, {}, express.Router); // Client: typed calls and outcomes const { apiClient } = makeApi(spec, { baseUrl: apiOrigin }); const result = await apiClient.accounts.create_post({ body: { name: &#34;Ada&#34; }, }); </code></pre></div>Business errors belong to the contract too. The handler can return the declared <code>&quot;Name already taken&quot;</code> case. The client receives it through the common error envelope with its payload type preserved. Consumers can handle expected failures using the interface they already share with the backend. <h2 id="check-the-boundary-at-runtime"> Check the boundary at runtime <a class="heading-link" href="#check-the-boundary-at-runtime"> Link to heading </a> </h2> The server validates incoming request fields against their schemas. The client parses successful response data against the response schema; development mode also checks controller output before sending it. These checks complement the types used during development. Shared contract versions remain part of rollout coordination when clients and services deploy independently. The design reduces drift between maintained definitions and exposes incompatible data at the checked boundaries. Built with TypeScript, Zod, Express, and fetch. Explore the <a href="https://github.com/apispects/core" class="external-link" target="_blank" rel="noopener">source on GitHub</a> or the <a href="/posts/ts-api-spec/" >earlier TypeScript walkthrough</a>.