Architecture Overview

CareBridge is a TypeScript fullstack monorepo. Its defining architectural idea is that all clinical data mutations flow through an event queue where the AI oversight layer evaluates the patient’s complete picture across specialties — not just the latest chart entry.

Data flow

Clinician enters data
        |
        v
   API Gateway (tRPC, Fastify)
        |
        v
 Clinical services (vitals, labs, meds, notes)
        |    saves to PostgreSQL
        |    emits to Redis queue
        v
  AI Oversight Worker (BullMQ)
        |
        +--> Deterministic rules (cross-specialty patterns, drug interactions, critical values)
        |         +--> Immediate critical flags
        |
        +--> LLM review (Claude API, full patient context)
                  +--> Nuanced clinical flags
        |
        v
 Notifications --> Clinician Portal (flags dashboard)

Decoupling data entry from AI processing is deliberate: clinicians never wait for the LLM, and BullMQ provides retries, rate limiting, and backpressure for free. See Design Decisions for the rationale.

Monorepo structure

carebridge/
|-- packages/    Shared libraries
|-- services/    Backend microservices
|-- apps/        Next.js frontends (clinician + patient portals)
|-- tooling/     Seed data + CLI scripts

Turborepo manages the build graph: packages/* -> services/* -> apps/*. Packages build before the services that depend on them, and services before apps.

Packages

Package	Responsibility
`@carebridge/shared-types`	Canonical TypeScript interfaces for the whole system (pure types, no runtime deps)
`@carebridge/db-schema`	Drizzle ORM schema, migrations, DB connection, PHI column encryption
`@carebridge/validators`	Zod schemas for every API input, shared by backend and frontend forms
`@carebridge/medical-logic`	Vital danger zones, lab validation, trend analysis
`@carebridge/ai-prompts`	Versioned Claude prompts + context builder (see ai-oversight)
`@carebridge/fhir-utils`	FHIR R4 format converters

Services

Service	Port	Responsibility
`api-gateway`	4000	tRPC entrypoint, JWT auth middleware, audit logging, CORS
`clinical-data`	—	Vitals, labs, medications, procedures CRUD + event emission
`clinical-notes`	—	SOAP / Progress note templates, versioning, signing
`ai-oversight`	—	Rules engine + LLM review + flag management (BullMQ worker)
`auth`	—	JWT authentication + session management
`patient-records`	—	Patient demographics + care-team management
`notifications`	—	Alert delivery (in-app, email, SMS)
`fhir-gateway`	—	FHIR R4 import/export
`scheduling`	—	Appointment scheduling

Worker health-check ports: ai-oversight 4001, notifications 4002, scheduling 4003.

Apps

clinician-portal (port 3000) — Next.js 15 app for physicians, nurses, and care coordinators. tRPC client + React Query. Surfaces the clinical flags dashboard.
patient-portal (port 3001) — Next.js 15 app for patients. Notably does not surface AI flags (a compliance requirement).

Tech stack

Layer	Technology
Monorepo	Turborepo + pnpm workspaces
Language	TypeScript (strict mode, ESM)
Backend framework	Fastify
API layer	tRPC (end-to-end types, no codegen)
Frontend	Next.js 15 + React 19
Database ORM	Drizzle ORM
Database	PostgreSQL 16
Job queue	BullMQ + Redis 7
Validation	Zod
AI review	Claude API (`@anthropic-ai/sdk`)

Source of truth

The authoritative architecture description is the README in the CareBridge repo. Service-specific designs live under docs/.

CareBridge Documentation

Explorer