The architectural choices that shape CareBridge, and why each was made. The authoritative list lives in the README; this page summarizes and cross-links.
Event-driven AI review
Clinical data entry is decoupled from AI processing via the Redis clinical-events queue. Clinicians never wait for the LLM, and BullMQ handles retries, rate limiting, and backpressure automatically. This is the backbone of the architecture.
Deterministic rules before LLM
Known patterns — drug interactions, critical vital values, the cross-specialty patterns — fire immediately with zero LLM cost or latency. The LLM only handles nuanced cases that rules cannot encode. This keeps the common path fast and cheap, and keeps the most safety-critical detections fully deterministic and auditable. See AI Oversight Layer.
Versioned prompts
@carebridge/ai-prompts tracks prompt versions like code (PROMPT_VERSION), enabling A/B testing, regression testing when model versions change, and controlled rollbacks if a new prompt produces worse output. This pairs with a formal clinical sign-off process for prompt edits.
tRPC end-to-end
Shared types flow between frontend and backend with no codegen step — API-call type errors surface at compile time.
Drizzle ORM
Schema-as-code with type inference. Migrations are plain SQL generated from the schema diff, not opaque ORM transformations.
FHIR identifier namespace
CareBridge-minted FHIR identifiers use a URL-form Identifier.system under https://carebridge.dev/fhir/sid, chosen because major EHRs (Epic, Cerner) recognise URL-form systems where ad-hoc urn: schemes are hostile to their matching heuristics. A legacy MRN namespace is documented for future EHR integrations ingesting historical bundles. See the FHIR interop doc.
CDS non-device by construction
Rather than treat regulatory classification as a downstream concern, CareBridge is engineered so the flag system stays within the FDA non-device CDS boundary: every flag is independently reviewable, AI flags require human review, and patients never see AI flags. The boundaries that would trigger device classification are explicitly out of scope. See Compliance and Safety and the CDS exemption memo.
Clinician bridge (scoped, future work)
A scoped design exists for a bedside “clinician bridge” — a zero-persistence, browser-only handoff that lets a family caregiver share a captured patient timeline with a clinician who has no EHR or CareBridge account. The bridge runs the same ai-oversight rules statelessly, holds no PHI past the tab session, and falls under the same CDS non-device posture. It is scope-only and not yet implemented. See the clinician-bridge MVP doc.
Project status
| Component | Status |
|---|---|
| DB schema + migrations | Complete |
| Seed data (DVT scenario) | Complete |
| AI oversight rules engine | Complete |
| AI oversight LLM review | Complete |
| clinical-data service | Complete |
| clinical-notes service | Complete |
| api-gateway | Complete |
| auth service | Complete |
| patient-records service | Complete |
| notifications service | Scaffolded |
| fhir-gateway service | Scaffolded |
| scheduling service | Scaffolded |
| clinician-portal UI | Scaffolded |
| patient-portal UI | Scaffolded |
See also: Architecture Overview, Developer Guide.