Status: Work in progress — The system is being designed incrementally, domain by domain, and proven through steel thread prototypes.
A systems integration blueprint for safety net benefits programs. Contract artifacts — OpenAPI specs, state machines, decision rules, metrics, and field metadata — define the full API surface for backend development. States adopt the blueprint, customize it with overlays, and build adapters to their vendor systems. Frontends develop against a mock server without waiting for a production backend.
Frontend harness packages (form engine, safety harness, harness designer) live in a separate repository: codeforamerica/safety-net-harness.
New here? Start with the Executive Summary for a one-page overview, the Blueprint Overview presentation for a detailed walkthrough, or the ORCA Data Explorer to browse the data model.
This repository contains the base contract artifacts, tooling, and documentation for the contract-driven architecture. It provides:
- Base contract artifacts — OpenAPI specs, state machine definitions, decision rules, metrics, and field metadata that define both data operations (REST) and behavioral operations (RPC)
- Conversion scripts — generate contract YAML from tables (spreadsheets) so business users can author requirements directly
- Validation — check OpenAPI specs and cross-artifact consistency
- Mock server — interprets contracts with an in-memory database for development without a production backend, serving REST APIs, RPC APIs, and event streams
- Field metadata — annotations (program relevance, verification requirements, regulatory citations), field-level permissions, and multilingual labels as contract artifacts served by the backend
- Client generation — typed TypeScript SDK and Zod schemas from resolved specs
- State overlays — states customize contracts without forking the base files
States create their own repositories, install the base packages (@codeforamerica/safety-net-blueprint-contracts, @codeforamerica/safety-net-blueprint-mock-server, @codeforamerica/safety-net-blueprint-clients), and apply overlays. See the State Setup Guide.
The architecture is being proven through steel thread prototypes that exercise the most complex parts of the design before domains are built out at scale.
Choose your path based on your role:
| Role | You want to... | Start here |
|---|---|---|
| UX Designer | Explore the data model and design reference | UX Designer Guide |
| Backend Developer | Author contracts, validate specs, build production adapters | Backend Developer Guide |
| Frontend Developer | Build UIs against REST and RPC APIs, use generated clients | Frontend Developer Guide |
| Tester | Run tests, write integration tests, test against the mock | Tester Guide |
npm install
# Set your state
export STATE=<your-state>
# Start mock server + Swagger UI
npm run mock:start:allVisit http://localhost:3000 for interactive API docs.
| Command | Description |
|---|---|
npm start |
Start mock server |
npm run mock:start:all |
Start mock server + Swagger UI |
npm run validate |
Validate OpenAPI specs |
npm run overlay:resolve |
Resolve state overlay (requires STATE) |
npm run api:new |
Scaffold a new API spec |
npm run mock:reset |
Reset database to example data |
npm test |
Run unit tests |
npm run test:integration |
Run integration tests (includes Postman/newman) |
- Contract-Driven Architecture — Contract artifacts, portability, adapter pattern
- Domain Design — Domain organization, entities, data flow
- API Architecture — API organization, operational concerns
- Roadmap — Phases, prototypes, future considerations
- Workflow Prototype — Behavioral contracts (state machine, rules, metrics)
- Application Review Prototype — Field metadata contracts and context-dependent review
- State Setup Guide — Set up a state repository with overlays and CI
- Creating APIs — Design new API specifications
- State Overlays — Customize contracts for state-specific needs
- Validation — Validate specs and fix errors
- Mock Server — Run and query the mock server
- Search Patterns — Search and filter syntax
- API Clients — Generated TypeScript clients
- CI/CD for Backend — Contract test your API implementation
- CI/CD for Frontend — Build and test frontend apps (in harness repo)
- Commands — All available npm scripts
- Project Structure — File layout and conventions
- Troubleshooting — Common issues and solutions
Node.js >= 20.19.0