Quick Start — 10 Minutes

1. Set Up Dev Environment (3 min)

Prerequisites

• Node.js 18+
• Docker (for local Postgres)
• Git

Start servers

# Clone and install
cd ~/REPOS/Stratum\ Collective/stratum-platform
npm install
cd web && npm install && cd ..

Start Postgres container
docker compose up -d

Start API server (port 3001)
npm run dev

In another terminal, start frontend (port 3088)
cd web && npm run dev

Visit:
• Frontend: http://localhost:3088
• API: http://localhost:3001
• Health check: http://localhost:3001/health

Environment files

.env (API)

DATABASE_URL=postgresql://stratum:stratum_dev_only@localhost:5432/stratum
NODE_ENV=development
PORT=3001

web/.env.local (Frontend)

NEXT_PUBLIC_API_URL=http://localhost:3001

2. Understand the Stack (3 min)

3. Core Concepts (4 min)

Multi-Tenancy

Every request includes a user ID (from X-User-Id header in Phase 1). The AuthContext middleware automatically filters all database queries by tenant. When adding routes: Always include the tenant middleware unless you're building a public endpoint (like /health or /api/registries).

Precedent Objects

The core domain model — a structured clinical denial decision with:
• What: Service/procedure, diagnosis, parity claim
• Why denied: Insurance denial reason, internal code
• Evidence: Source documents, clinical guidelines
• Outcome: Appeal overturned? Win rate by payer?
Stored in precedent_objects table. Updates snapshot to precedent_version_history (immutable, never overwrite).

Payer Plans

Reference data lookup — "What does [payer]'s plan say about [service]?"
• Stored in payer_plans table
• Indexed by payer, year, state
• coverage_data is JSONB for flexible schema evolution

Marketplace

A network effect: clusters of related precedents enable discovery and sharing.
• Cluster: Group of related precedents (e.g., all "utilization review denial" cases for Cigna)
• Maturity: Clusters only appear in marketplace after 2+ distinct tenants contribute (network effect gate)
• Credit: Contributors earn credits for precedents. Credits can be redeemed for queries.

Compliance

PHI Validation: All request bodies are scanned for SSN, phone, MRN, etc. If detected, request rejected with 422. Deidentification: Safe Harbor removal of 18 identifiers for data export. Admins only, requires ?deidentify=true flag. 42 CFR Part 2: Substance use disorder data has special rules — sharing requires consent_required: true or originator_only: true tags.

4. Common Tasks

Add a New API Endpoint

• Define Zod schema in src/utils/validation.ts
• Add route handler in src/routes/.ts
• Include tenant middleware to filter by tenant
• Test with npm test
• Document in API Reference
See New Endpoint Checklist for detailed steps.

Add a Frontend Page

• Create web/src/app/[path]/page.tsx
• Use Next.js App Router conventions
• Fetch from API at process.env.NEXT_PUBLIC_API_URL
• Follow Design System (dark clinical theme)
• Test responsive at mobile/tablet/desktop
See New Page Checklist for detailed steps.

Query the Database

Use the pool from src/db/connection.ts:

import { pool } from '../db/connection';

const result = await pool.query(
  'SELECT  FROM precedent_objects WHERE tenant_id = $1',
  [tenantId]
);

For transactions:

await withTransaction(async (client) => {
  await client.query('INSERT INTO precedent_objects ...');
  await client.query('INSERT INTO precedent_version_history ...');
});

See Database Patterns for more.

Validate Input

Use Zod schemas:

import { createPrecedentSchema } from '../utils/validation';

const validated = createPrecedentSchema.parse(req.body);
// throws ZodError if invalid → Express error handler → 422 response

See Validation Patterns for details.

5. File Structure

src/
  server.ts                      # Express entry point
  types/index.ts                 # All TypeScript types, enums
  db/
    schema.sql                   # Table definitions (11 tables)
    connection.ts                # Pool, helpers, transactions
    migrate.ts                   # Run migrations on startup
  middleware/
    tenant.ts                    # AuthContext, X-User-Id lookup
    phi-validation.ts            # Reject requests with SSN, etc.
    deidentify.ts                # Safe Harbor 18-identifier removal
    audit.ts                     # Log events to audit table
  routes/
    precedents.ts                # CRUD, versioning, export
    payer-plans.ts               # Plan lookup, drift detection
    appeals.ts                   # Appeal lifecycle
    marketplace.ts               # Cluster discovery, scoring
    validation.ts                # Validation gates
    registries.ts                # Read-only registry queries
  services/                      # Business logic
  registries/index.ts            # Load JSON registries
  utils/validation.ts            # Zod schemas for all requests
web/
  src/app/                       # Next.js App Router
    layout.tsx                   # Root layout, Tailwind setup
    library/                     # Precedent library page
    [other routes]/              # Other app pages
  src/components/                # Reusable React components
  src/lib/                       # Utilities, API client hooks

6. Key URLs

Layer	Technology	Purpose
API	Express 5 + TypeScript	REST endpoints, business logic, database
Database	Postgres 16	Multi-tenant storage, HIPAA-compliant
Frontend	Next.js 16 + React 19	Web UI, clinical dark theme
Deploy	Fly.io (API) + Cloudflare Workers (Frontend)	Production hosting
Environment	URL	Purpose
Local	http://localhost:3001	API dev server
Local	http://localhost:3088	Frontend dev server
Production API	https://stratum-platform-api.fly.dev	Fly.io hosted API
Production Frontend	https://platform.stratumcollective.co	Cloudflare Workers

7. Next Steps

• Building something? Follow the appropriate checklist for your task
• Understanding a system? Jump to Architecture or Core Systems
• Need help? Check FAQ or Troubleshooting