Architecture
Architecture
How the platform is put together — services, data plane, trust boundaries, and the decisions behind them.
Owner: Platform EngineeringLast reviewed:
The platform is a set of BFF-style Next.js apps in front of a Go modular
monolith (core-api) with focused satellite services, all running on a
Canadian-hosted RKE2 cluster. Async work flows through NATS JetStream; AI calls
leave the cluster only through the single ai-gateway.
Pages in this section
- System architecture — the runtime topology diagram: how the Next.js apps, core-api, the data plane, the worker, and the AI gateway connect.
- System overview — the canonical
document (mirrored from
docs/architecture/system-overview.md): service responsibilities, trust boundaries, primary data flows, environments, and degraded modes. - Implementation plan — delivery phases 0–9 and the definition of working for each.
- Decision records (ADR) — all accepted ADRs,
mirrored from
docs/adr/in the repo. Start with ADR 0001 (monorepo) and ADR 0002 (modular monolith).
Ground rules worth memorizing
- Only
ai-gatewaymay call OpenAI (store: false, gated byAI_PHI_MODE) — nevercore-api, never a browser. - Tenant isolation is enforced in PostgreSQL with row-level security, not just application code.
- Transcripts, notes, plans, templates, and documents are immutably versioned; approvals and audit events form a hash chain.
- Browsers never hold tokens: the Next.js apps keep encrypted HttpOnly session cookies and attach access tokens server-side.