Developer Guide

How to set up, run, and extend CareBridge. The authoritative reference is the README; this page is the working summary.

Prerequisites

Node.js 20+
pnpm 9+ (npm install -g pnpm)
Docker and Docker Compose

Setup

git clone https://github.com/blamechris/carebridge.git
cd carebridge
pnpm install
cp .env.example .env       # set DATABASE_URL, REDIS_URL, ANTHROPIC_API_KEY, JWT_SECRET, ...
docker-compose up -d       # PostgreSQL 16 + Redis 7
pnpm db:migrate
pnpm db:seed               # seeds the DVT-scenario patient (Margaret Chen)
pnpm dev                   # all services + apps, hot reload

pnpm dev runs tsc --watch for every @carebridge/* library alongside tsx watch for each service. Editing a package’s src/ rebuilds its dist/ and the consuming service hot-reloads. If a fix is on disk but not taking effect at runtime, check that the package’s dist/ mtime is newer than its src/.

Running services

Service	URL
API Gateway	http://localhost:4000
API Health	http://localhost:4000/health
Clinician Portal	http://localhost:3000
Patient Portal	http://localhost:3001

Key commands

pnpm dev             # start all services + apps (persistent, hot reload)
pnpm build           # build all packages, services, apps
pnpm typecheck       # TypeScript checking across all packages
pnpm lint            # ESLint across all packages
pnpm db:generate     # generate Drizzle migrations from schema changes
pnpm db:migrate      # apply pending migrations
pnpm db:seed         # re-seed development data
pnpm clean           # remove all dist/ directories

Environment variables

A subset of the most load-bearing values; the full table (boot-required, production-required, key-rotation, Redis, observability, clinical-rule tuning, dev-mode) is in the README.

Variable	Notes
`DATABASE_URL`	PostgreSQL connection string (boot-required)
`JWT_SECRET`	Signs JWTs; throws on missing
`PHI_ENCRYPTION_KEY`	64-char hex (32 bytes) for AES-256 PHI column encryption; throws on missing
`ANTHROPIC_API_KEY`	Claude API key for the LLM review pipeline
`SESSION_SECRET` / `PHI_HMAC_KEY`	Production-required; throw when `NODE_ENV=production`
`CAREBRIDGE_DEV_AUTH`	`"true"` (non-production) enables the `x-dev-user-id` header bypass for local dev

PHI key rotation is a documented runbook — see the PHI key rotation doc and Compliance and Safety.

Code conventions

TypeScript strict mode everywhere
ESM — type: "module" in every package.json, .js extensions in imports
Functional style — prefer functions over classes
Dates — always ISO 8601 strings (new Date().toISOString())
UUIDs — crypto.randomUUID() (no external packages)
Workspace packages — import as @carebridge/*

Commit format

type(scope): short summary in present tense

Types: feat, fix, refactor, docs, test, chore, style, perf. Scopes: db, ai, notes, clinical, auth, gateway, portal, infra.

Extending the system

Adding a migration

Edit packages/db-schema/src/schema/ to modify tables.
pnpm db:generate to generate the migration SQL.
pnpm db:migrate to apply it.

Adding a clinical rule

Rules live in services/ai-oversight/src/rules/. Add an entry to cross-specialty.ts (or a new file) following the existing pattern:

{
  id: "RULE-ID-001",
  evaluate(context: ReviewContext): RuleResult | null {
    // return null if the rule doesn't apply
    // return { severity, category, summary, rationale, suggested_action } if it does
  }
}

Rules evaluate synchronously before the LLM review, so they fire with zero additional latency. See AI Oversight Layer.

Editing AI prompts

Changes to clinical prompt data (drug-class cross-reactions, the system/user prompt) require a formal sign-off: a primary-source citation, a PROMPT_VERSION bump, test coverage, and a downstream-impact check. Full checklist in the AI prompt editing doc. Validate prompt assembly with the golden-eval harness.

Build pipeline

Turborepo manages the graph: packages/* -> services/* -> apps/*. The dev task runs persistently with no cache.

CareBridge Documentation

Explorer