Chapter 03 / 14

System architecture

Maintained surfaces

PWA/ is the browser experience built primarily in Python through PyScript. OPS/ is the operator interface. API/ is a Sanic gateway and the only application component allowed to authorize durable actions. OTA/ serves signed Android update discovery and bundles. documents/slides/ and documents/docs/ are static deployments generated from Python sources.

Public service topology

The diagram below is a public boundary map, not an infrastructure runbook. It shows which maintained surface may make a bounded request to another component; it intentionally omits hostnames, credentials, network placement, defensive thresholds, and private operator paths. The documentation and slide deployments are static and do not receive database, Redis, provider, signing, or mutation credentials.

Request path

1. A browser or native shell sends a bounded request to Sanic. 2. Middleware establishes correlation, concurrency, CORS, authentication, logging, and a request-local database transaction. 3. A service executes deterministic rules or asks a provider through a narrow interface. 4. Tool proposals pass authorization and idempotency before any side effect. 5. The response is streamed or returned; the transaction commits only at the lifecycle boundary.

Data and provider boundaries

Neon Postgres owns durable relational state. Redis owns revocable/session-like coordination and queues when configured. Speech-to-text, model, text-to-speech, cloning, telephony, address, mail, and storage are adapters: vendor-specific transports sit behind Python protocols. Synthetic adapters make contracts testable without implying vendor readiness.

Sanic is the enforcement boundary between untrusted clients and durable or external effects. A model can return structured proposals, but only trusted backend code evaluates authorization, consent, idempotency, and provider policy before an effect. OTA delivers signed Android bundles to the PWA update client; it is not an application data path.

Streaming voice sequence

Audio frames flow to STT; transcript deltas flow to the model; structured tool proposals pause for backend authorization; response deltas flow to TTS; audio frames return to the caller. Bounded queues, deadlines, cancellation, and backpressure prevent one slow component from owning the whole process.