← Back to Platform Architecture
Stratum Platform Documentation
Welcome to the single source of truth for Stratum Platform technical architecture, API design, data models, compliance patterns, and development conventions.
Quick Navigation by Role
I'm a Backend Developer
Want to: Add a new API endpoint or modify business logic
Start here:
QUICK-START — 10-minute onboarding
API Design Principles — How APIs are structured
New Endpoint Checklist — Step-by-step guide
Data Models Overview — Available tables and schemas
Patterns & Conventions — How to write code correctly
I'm a Frontend Developer
Want to: Build UI for a feature
Start here:
QUICK-START — 10-minute onboarding
Frontend Architecture — Next.js 16, App Router structure
New Page Checklist — Step-by-step guide
API Endpoints — What data endpoints return
Design System — Components, colors, typography
I'm Implementing a Feature
Want to: Build something end-to-end (database → API → frontend)
Start here:
Payerplan Case Study — Real worked example
New Endpoint Checklist — Backend steps
New Page Checklist — Frontend steps
Compliance Gate Checklist — Security & HIPAA
I'm Ensuring Compliance
Want to: Understand HIPAA, PHI handling, audit requirements
Start here:
Compliance Architecture — System-wide design
PHI Validation — What gets blocked on inbound
Deidentification — Data export safety
Audit Log — What gets logged and for how long
Compliance Status — Current phase, gaps, roadmap
I'm Deploying or Operating
Want to: Deploy, monitor, debug in production
Start here:
Deployment Guide — Fly.io, Cloudflare setup
Architecture Overview — System diagram, components
Troubleshooting — Known issues and fixes
Debugging — How to investigate problems
Documentation Structure
docs/
├── 00-README.md (YOU ARE HERE)
├── 00-QUICK-START.md (10-min onboarding)
├── 01-ARCHITECTURE/ (System design, compliance, deployment)
│ ├── OVERVIEW.md System block diagram, deployment model
│ ├── STACK.md Tech decisions and rationale
│ ├── COMPLIANCE-ARCHITECTURE.md HIPAA, 42 CFR Part 2 design patterns
│ ├── MULTI-TENANCY.md Tenant isolation, AuthContext, auth flow
│ └── DEPLOYMENT.md Fly.io, Cloudflare, Docker, migrations
├── 02-DATA-MODELS/ (11 tables, schemas, indexes)
│ ├── OVERVIEW.md ER diagram, table relationships
│ ├── PRECEDENTS.md Core domain model, all §1-§12 SCIA fields
│ ├── VERSIONING-IMMUTABILITY.md precedent_version_history design
│ ├── PAYER-PLANS.md Plan lookup, coverage_data JSONB
│ ├── APPEALS.md Appeal lifecycle, state machine
│ ├── MARKETPLACE.md marketplace_clusters, contribution_scores
│ ├── CREDITS.md Event-sourced ledger, mint/burn
│ ├── AUDIT.md compliance logging, retention
│ └── INDEXES-PERFORMANCE.md Index strategy, query optimization
├── 03-API-REFERENCE/ (30+ endpoints, design, error handling)
│ ├── OVERVIEW.md Design principles, versioning
│ ├── AUTHENTICATION.md X-User-Id header, Auth0 roadmap
│ ├── ENDPOINTS-PRECEDENTS.md CRUD, versioning, export, ?deidentify=true
│ ├── ENDPOINTS-PAYER-PLANS.md Coverage lookup, drift detection
│ ├── ENDPOINTS-APPEALS.md Lifecycle, validation, submission
│ ├── ENDPOINTS-MARKETPLACE.md Cluster discovery, profile, purchase
│ ├── ENDPOINTS-VALIDATION.md Validation gates, quality checks
│ ├── ENDPOINTS-REGISTRIES.md Read-only registry queries
│ ├── ERROR-HANDLING.md Error codes, HTTP semantics
│ └── PAGINATION-FILTERING.md limit, offset, sorting, filtering
├── 04-CORE-SYSTEMS/ (Business logic, compliance)
│ ├── MARKETPLACE.md Clustering logic, maturity tiers
│ ├── CREDIT-ECONOMY.md Mint/burn, allocation, scoring
│ ├── PREVENTION-RULES-ENGINE.md v0 validation gates (PR-U1 to PR-D5)
│ ├── PHI-VALIDATION.md 18 identifiers, 42 CFR Part 2 SUD
│ ├── DEIDENTIFICATION.md Safe Harbor 18-identifier stripping
│ └── APPEAL-BUILDER.md Narrative assembly, evidence kit
├── 05-REGISTRIES/ (15+ reference data registries)
│ ├── OVERVIEW.md Registry architecture, loading strategy
│ ├── PAYER-REGISTRY.md PayerRecord schema, fields, usage
│ ├── DENIAL-REASON-REGISTRY.md X.12 code mapping, categories
│ ├── STATE-BEHAVIORAL-HEALTH.md By-state metrics, parity violations
│ ├── MEDICAID-PRECEDENTS.md State-specific success rates
│ ├── ACADEMIC-RESEARCH.md Evidence basis registry
│ └── REGISTRY-MAINTENANCE.md Update process, governance, cadence
├── 06-FRONTEND/ (Next.js, design system, components)
│ ├── ARCHITECTURE.md Next.js 16, App Router, layout structure
│ ├── DESIGN-SYSTEM.md Tailwind, dark clinical theme
│ ├── COMPONENTS.md Reusable component library, patterns
│ ├── PAGES-STRUCTURE.md App modules and route organization
│ ├── STATE-MANAGEMENT.md API hooks, data fetching patterns
│ ├── TESTING.md Vitest setup, test patterns
│ └── DEPLOYMENT.md Cloudflare Workers, OpenNext build
├── 07-PATTERNS-CONVENTIONS/ (Coding standards, architectures)
│ ├── DATABASE-PATTERNS.md Multi-tenancy, query helpers, transactions
│ ├── VALIDATION-PATTERNS.md Zod schemas, 422 vs 400 semantics
│ ├── ERROR-HANDLING-PATTERNS.md Error codes, logging, observability
│ ├── TESTING-PATTERNS.md Unit, integration, fixture patterns
│ ├── CODE-ORGANIZATION.md File structure, imports/exports
│ ├── NAMING-CONVENTIONS.md Variables, functions, types
│ └── GIT-WORKFLOW.md Branching, commit messages, reviews
├── 08-FEATURE-IMPL-GUIDE/ (Checklists, case studies)
│ ├── PAYERPLAN-CASE-STUDY.md End-to-end example: schema → API → frontend
│ ├── NEW-ENDPOINT-CHECKLIST.md Step-by-step guide to add API endpoint
│ ├── NEW-FRONTEND-PAGE-CHECKLIST.md Step-by-step guide to add page
│ ├── NEW-REGISTRY-CHECKLIST.md Step-by-step guide to add registry
│ └── COMPLIANCE-GATE-CHECKLIST.md PHI validation, SUD, audit logging
├── 09-TROUBLESHOOTING/ (Common issues, debugging, FAQ)
│ ├── COMMON-ISSUES.md Dev environment, migrations, Fly.io
│ ├── DEBUGGING.md Console, logs, network, database
│ └── FAQ.md Frequently asked questions
└── 10-GOVERNANCE/ (Compliance, decisions, deprecation)
├── COMPLIANCE-STATUS.md Phase, blockers, roadmap
├── DECISION-LOG.md Architecture decision records (ADRs)
└── DEPRECATION-POLICY.md How to sunset patterns
Key Principles
Single Source of Truth — All technical documentation lives in this repo folder, not scattered across Notion or wiki pages
Hierarchical Navigation — Documents are organized by audience and topic, with clear "See also" links between related docs
Code-Adjacent — Every system documented here has implementation references pointing to actual code files
Audience-Focused — Documentation is organized around what role you play (backend, frontend, compliance, ops), not by technology
Maintained with Code — Documentation updates are part of code review; patterns and APIs are documented before implementation
Getting Started
New to this codebase? Start with QUICK-START
Want to build something? Find your role above and follow the links
Need to understand how something works? Use the "See also" sections to jump between related docs
Implementing a feature? Start with the Payerplan Case Study, then follow the appropriate checklist
Contributing to Documentation
When adding code, update docs too:
See DECISION-LOG.md for major architectural choices and DEPRECATION-POLICY.md for how to retire patterns.