Architecture

The parts#

The browser never holds a security token. The web application keeps the session server-side in an encrypted cookie (iron-session, split over up to eight cookies of about 3.5 KB each) and injects the bearer token when it proxies to the API, refreshing the pair and retrying once when the API refuses an expired token. Client-side script cannot read it. Everything under /api/v1 that is not one of the few explicit sign-in handlers goes through one catch-all proxy, and nothing the browser sends names the workspace: the API binds it from the session's own access profile.

The modules#

The API is a modular monolith. Every module has the same four layers, behind one public entry point (index.ts), wired by its own composition.ts:

modules/<scope>/<module>/
├── domain/          entities, state machines, invariants: no I/O
├── application/     use cases, depending on ports they declare
├── infrastructure/  adapters: repositories, gateways, clocks
└── interface/       controllers, routes, request schemas

Dependencies point inward. The domain layer does no I/O, so every state machine and invariant is unit-testable without a database. Modules never reach into one another's layers: they talk through public types, the in-process event bus and the database's own gates.

Platform scope (what an organization is made of)#

Study scope (what a study is made of)#

The platform console's modules#

admins, audit, auth, organizations and stats: small modules of the control plane, with no clinical data (Platform console).

What a request meets#

The order is deliberate: the audit hook is armed before anything that can reject, so a request refused by the limiter or by a malformed body is still audited; the limiter runs before the parser so an abusive client cannot extract a full parse. Study-scoped routes then pass through a chain before any module sees them:

This is the order on Who can and cannot, and the layer that stops a request gives the refusal, so a person who is not allowed never learns the state of a study. A person who is not a member of a study gets not found, not forbidden. The study-state check is applied at the mount (version_work, cleaning, governance, metadata intents) rather than remembered route by route, after an early finding that design routers accepted writes on a locked study. Every operation declares its access, and a route-coverage test holds every registered screen to a permission; a screen that is not in the registry is unreachable.

Durable work: nothing is only in memory#

Work that must not be lost is written to tables, in the same transaction as the change that causes it, and carried out by the worker:

The worker also verifies the audit chains (every hour from each chain's last checkpoint, and in full once a week), makes the ledger's monthly partitions ahead of time, anchors each chain's end once a day in storage that cannot be rewritten (S3 Object Lock in compliance mode: production refuses to start without it unless AUDIT_ANCHOR_REQUIRED is switched off), and sweeps operational health every minute: audit outbox lag or dead letters, mail not leaving, summary lag, export jobs claimed by a worker that stopped, and backups that are stale or never verified. A condition raises an alert (an e-mail to ALERT_EMAILS) and clears itself when it recovers (Running it). Domain events themselves travel an in-process bus that is not durable; that is why nothing that matters depends on it alone.

Observability#

Structured JSON logs (pino) with credentials redacted, correlated by a request id carried through async-local storage; GET /healthz (liveness) and GET /readyz (readiness, 503 when the database is unreachable) ahead of authentication; GET /api/v1/_internal/info for the operator (needs system.monitor). Metrics and tracing are not emitted: the metrics interface is a no-op and no tracing library is wired.

What is not production-grade yet#

• One API process and one worker. The deployment runs each as a single PM2 process; the API's rate-limit counters live in its memory, so they are per process. Running several API processes needs a shared store for the limiter first.
• The generic job queue is a stub. infrastructure/queue is an in-memory queue that carries no work today; everything durable uses the tables above. There is no Redis in the application.
• No metrics, no distributed tracing. Operators rely on logs, the probes and the alerts.
• The event bus is in-process. Audit and mail are durable through their outboxes; notifications are not.

Related#

Data and tenancy · Environments and versioning · Running it · The database · Architecture decisions · Security and hosting