Architecture overview
Architecture overview
Section titled “Architecture overview”ForgeGuard Kokoro Server is a FastAPI application that wraps the Kokoro-82M model behind an OpenAI-compatible HTTP interface, with an authentication and readiness gate in front of synthesis and a streaming audio encoder behind it.
Components
Section titled “Components”- FastAPI interface — routes: OpenAI-compatible endpoints under
/v1, extended endpoints under/devand/debug, the web console under/web, and the unauthenticated/health,/ready, and/system. - Auth + readiness gate — a dependency that enforces the optional
API_KEYand short-circuits synthesis routes with503while the model is warming or after a failed warmup. See Health and readiness. - TTS service — resolves the voice (including weighted combinations), chunks long input at sentence boundaries, and drives inference.
- Kokoro model + voice pipelines — the Kokoro-82M backend and per-language grapheme-to-phoneme pipelines that produce audio frames.
- Streaming audio writer — encodes frames into
mp3,wav,opus,flac, or rawpcm, either streamed or as a complete response. - Health + system telemetry — liveness/readiness plus GPU and activity telemetry for operators and the console.
Trust boundary
Section titled “Trust boundary”The trust boundary is the HTTP interface. When API_KEY is set, /v1, /dev, and
/debug require a bearer token; /health, /ready, /system, and /web are always
open by design. The server makes no external network calls at runtime — the model and
voices are baked in and offline flags are set. See
Security hardening.
Persistence boundary
Section titled “Persistence boundary”The server is effectively stateless. Synthesized audio is streamed back to the client;
anything written to disk lives under OUTPUT_DIR (generated files and, with built-in
TLS, the self-signed certificate) plus a short-lived temp directory that is
garbage-collected. Unless you mount a volume at OUTPUT_DIR, that storage is ephemeral.