Faurenis architecture specification

Faurenis assists licensed dental clinicians with documentation, charting, evidence lookup and practice operations. It drafts; the clinician decides, and nothing it drafts reaches the record without a clinician action. Each AI feature is registered with a written intended purpose, input, output and automation level, and the build fails if a new AI route is not registered.

Eight rules decide every architectural trade-off in Faurenis, and each is enforced by code, a database constraint or a CI gate rather than by convention. Behind them sit numbered clinical invariants — for artifacts, tenant isolation, recovery, Scribe, Perio, evidence and voice — that a change must not regress. A regression against any of them stops a pull request, regardless of what else it delivers.

One application service on Cloud Run — a Node.js modular monolith — serves the web app and its API, backed by Cloud SQL PostgreSQL 16, Cloud Storage and Cloud KMS. Work that needs different hardware or a hard isolation boundary runs as a small number of satellite services: a document renderer, an imaging pre-processor, and GPU inference workers. Everything runs in approved EU regions; there is no message broker — asynchronous work is carried by Postgres outboxes drained on a schedule.

The application is a modular monolith: domains are separated by module boundaries and lint rules, not by network hops, which keeps a clinical transaction in one database transaction. Every request passes a fixed middleware chain, and every AI request additionally passes compliance, consent, budget, audit and output-scanning gates before a model is called. The HTTP surface — 700+ routes — is described by a generated manifest that CI checks on every change.

Every module plugs into the same spine: one encounter per visit, a governed lifecycle for everything AI produces, a fact layer that only clinician-confirmed data can enter, and an audit and provenance trail behind all of it. This is what makes Faurenis one application rather than a set of AI features: Scribe, Perio, Copilot, Imaging and Documents all write through the same rails, so review, finalization and correction work identically everywhere. The spine contains no AI; it is the deterministic structure the AI works inside.

Faurenis is 19 modules in six domains — capture, reason, see, produce, operate and govern — all writing through the clinical spine. Every module is specified on one template: purpose, pipeline, data owned, models, guardrails, rollout status, interfaces, invariants and known limits. A module that makes no model calls says so explicitly; most of the operational modules are deterministic code.

Every model call in Faurenis goes through one routing layer: endpoints map to capability tiers, tiers map to models, and a retry engine falls back one tier down rather than failing. Hosted Gemini models on Vertex AI in the EU serve production traffic; a self-hosted estate of open-weight clinical models, embeddings and entailment on GPUs is rolling out beside them, with Vertex as its fallback. Around every call sits a layered guardrail stack — consent, budget, PII stripping, schema validation, output rules, deterministic red-flag checks and a decision record — so no model output reaches a clinician unchecked.

Models improve from one signal: what clinicians kept, changed or rejected. Those decisions are exported de-identified, used to fine-tune small open-weight adapters, evaluated against locked sets with clinician sign-off, and released only as signed packages that three roles approve. A release reaches clinicians in stages — shadow, then pilot, then clinical — and any change to the files that define a model’s behaviour invalidates its sign-off automatically. The export, evaluation harness and release control plane are built; adapter training and the self-hosted deployment are rolling out now.

One relational system of record — Cloud SQL PostgreSQL 16 with 220+ tables — holds the clinical plane, with object storage for images and documents and a physically separate database for research. Identifying fields are encrypted per patient under keys wrapped by a per-clinic key in Cloud KMS, and searchable through keyed hashes rather than plaintext. Erasure is engineered for backups as well as the live database: erasure tombstones are replayed after any restore, and destroying a clinic key makes every backup of that clinic unreadable.

Tenant isolation is enforced by PostgreSQL itself: every tenant table forces row-level security keyed on a clinic id that is set per transaction from the authenticated session, never from the request. Static lints prove every table is covered and every route uses a scoped connection, and an adversarial cross-tenant suite runs in CI on every change. Around that sit layered controls — signed short-lived tokens, MFA, a strict content security policy, upload scanning, a web application firewall — and a written STRIDE threat model with a residual-risk register.

Every production deploy goes blue-green: a new revision is health-checked with no traffic before traffic moves, and rollback is redeploying the previous revision against a schema that only ever expands. Recovery is rehearsed on a schedule — a weekly restore drill from backup and a weekly resilience drill that injects provider outages, slow dependencies, database failover and crashes. Capacity, timeouts and alerts are written down as numbers, and every scheduled job records its runs.

Faurenis keeps its quality system in the repository as machine-checked registries: 126 requirements, 129 hazards, 121 mitigations and 52 verifications, traced to each other and to the code. The engineering lifecycle is mapped to IEC 62304, risk management to ISO 14971 and the design history to ISO 13485, and every AI feature carries a written intended purpose. Regulatory classification is a legal determination that has not been made; the platform is built as if the stricter outcome applies.

Code reaches production through one pipeline, shared by human and AI contributors: plan, implement with tests, a focused safety audit, an independent AI code review against the clinical invariants, then 20+ CI workflows and 40+ one-way ratchets. Ratchets let quality move in one direction only — a file may shrink but not grow past its limit, an `any` count may fall but not rise, a snapshot of exceptions may only lose entries. Guards are themselves tested: a check that cannot observe its own failure is treated as a defect.

This chapter lists what is not built, not enabled or not yet evidenced, in one place. Every item also appears in the chapter it belongs to; collecting them here is so that nobody has to infer the gaps from what the other chapters leave out. A gap that is written down gets scheduled; a gap that is implied does not.

All 32 architecture decision records, with their status as each record states it: 28 accepted and 4 proposed. The index is generated from `docs/adr/`, so a new decision appears here in the same change that adds it.

Terms used across this specification, with the Croatian term clinicians see in the product. Status words follow the five-status vocabulary: Production, Pilot, Shadow, Rolling out, Planned.