Architecture

A bird's-eye view of how Bigwave's components fit together. Read this once before customising anything.

High-level shape

Bigwave is a single FastAPI process behind a Compose stack:

            ┌──────────────────┐
            │     Web UI       │  React/Vite, served at :8080
            └────────┬─────────┘
                     │
                     ▼
   ┌─────────────────────────────────────────┐
   │           apps/api (FastAPI)             │  :8000
   │                                           │
   │  /v1/chat/completions   /v1/embeddings    │
   │  /v1/models             /healthz          │
   │  /admin/*               /webhooks/*       │
   └────┬──────┬──────┬──────┬──────┬──────┬──┘
        │      │      │      │      │      │
        ▼      ▼      ▼      ▼      ▼      ▼
     gateway  serving  storage  eval  guardrail  channels
        │      │        │      │        │        │
        ▼      ▼        ▼      ▼        ▼        ▼
     fallback ollama  sqlite/  golden_  noop /  telegram /
     chain    or vllm postgres set,    dsl     slack
                              gate

Each box on the bottom row is an ABC with multiple in-tree adapters; the operator selects which adapters run via ./install.sh flags. See optional-by-design adapters for the full vocabulary.

Request lifecycle

A /v1/chat/completions request walks the following pipeline:

1. Auth — require_bearer_token resolves the bearer to a Principal (with workspace + roles); proxy_headers adapter is the alternative when a reverse proxy fronts bigwave.
2. Rate limit — per-workspace token-bucket (enforce_workspace_rate_limit); 429 with Retry-After if the bucket is dry.
3. Guardrail (input) — DSL provider checks the last user message against the workspace policy; Block short-circuits with OpenAI finish_reason="content_filter".
4. RAG injection (optional) — when bigwave_kb_id is set, the gateway fetches workspace-scoped chunks from the vector store and prepends them as a system message.
5. Engine dispatch — chat_with_fallback peeks the first chunk from the primary model. On pre-stream failure it re-tries the next handle in the fallback chain. Mid-stream errors propagate.
6. Streaming response — SSE chunks land back to the client; the InferenceLog spy captures the assembled response text + token counts for observability.
7. Provenance + audit — CompletionProvenanceCache records (completion_id → workspace, model, adapter, prompt template) so the feedback submit endpoint can resolve later. The InferenceLog row persists on stack drain.

Key invariants

• Workspace fence. Every storage repository takes a workspace_id parameter; cross-tenant fetches return 404 (never 403 — no count-oracle leak). This is enforced at the repository layer, not the route.
• Rollback semantics on activation. When ReplicaManager.activate fails — gate block, drain timeout, engine load failure — the old handle stays live. There is no half-broken state.
• Audit append-only. AuditLogRepository.record is the only write path; nothing in tree updates or deletes audit rows.
• License-check on the runtime path. scripts/license-check.py runs in CI. GPL/AGPL on the runtime path fails the build.

Where each piece lives

Component	Path
FastAPI composition root	apps/api/main.py
Lifespan wiring	apps/api/lifespan.py
Settings / env vars	apps/api/config.py
Web UI	apps/web/src/
Gateway routes	packages/gateway/adapters/firstparty/routes.py
Serving (engine, ReplicaManager)	packages/serving/
Training (TrainingBackend, registry)	packages/training/
Eval (Scorer, Suite, Runner, Gate)	packages/eval/
Storage backends	packages/shared/db/adapters/
Channels (Telegram, Slack)	packages/channels/
Guardrails (noop, DSL)	packages/guardrails/
Observability (stdout, Phoenix)	packages/shared/observability/
Audit log	packages/shared/audit.py
Rate limit	packages/shared/rate_limit.py

Reading order for newcomers

1. docs/charter.md — the long-form thesis.
2. docs/architecture.md — system-design depth (you are here, abridged).
3. docs/adr/ — the architecture decisions and why we made them.
4. docs/prd/ — per-component product requirements.
5. AGENTS.md — repo conventions, non-negotiables, parallel-worktree workflow.

Reading order for production deployment

1. Getting started — prove the loop on your laptop first.
2. Configuration reference — every knob.
3. Docker Compose deploy — production patterns.
4. Use cases — match your buyer outcome to a recipe.