Skip to content

Infrastructure and Local Operations

Topology

flowchart LR
  classDef default fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
  classDef highlight fill:#065f46,stroke:#34d399,stroke-width:2px,color:#f0fdf4
  Browser["Chrome or Edge"]:::highlight --> Static["Static Vite assets"]
  Browser --> Worker["Web Worker + AudioWorklet"]
  Browser --> CDN["Hugging Face model CDN"]
  Static --> Browser
  linkStyle default stroke:#64748b,stroke-width:2px

The production topology is static hosting plus browser-to-model-CDN downloads. Vite development runs on port 5173. vite.config.ts and vercel.json configure COOP/COEP headers for cross-origin isolation and threaded ONNX WASM.

Commands

pnpm install
pnpm dev
pnpm build
pnpm test
pnpm test:parsers
pnpm test:tools

pnpm build runs tsc -b before vite build. The dossier Makefile provides MkDocs build and consolidation targets.

Operational requirements

  • Chrome/Edge with WebGPU is the preferred runtime.
  • Microphone access requires a secure context, except localhost.
  • Model selection controls memory and download requirements; the README estimates roughly 6 GB available RAM for the full stack.
  • Static hosting must preserve worker files and cross-origin isolation headers.
  • Browser console logs are the primary runtime diagnostic channel; the app also exposes debug status and load progress.

Deployment tradeoff

Static deployment is inexpensive and privacy-preserving, but model downloads, browser cache eviction, WebGPU support, and device memory are outside the application’s operational control.

Asset and header contract

The static host must serve public/stt-worker-esm.js and public/vad-processor.js at stable root paths. It must also send:

  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp

These headers are configured for Vite dev and preview and mirrored in vercel.json. A host that omits them can appear to work while silently losing threaded WASM performance.

Deployment checklist

  1. Build with the same Vite target used for production.
  2. Verify worker paths and model CDN access.
  3. Verify cross-origin isolation with crossOriginIsolated.
  4. Test microphone permission on HTTPS.
  5. Test one small STT, LLM, and TTS preset before advertising larger models.
  6. Confirm browser cache behavior and a reset/recovery path.