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 form definitions — define the full API surface for both backend and frontend development. States adopt the blueprint, customize it with overlays, and build adapters to their vendor systems. Frontends develop against a mock server and declarative form definitions without waiting for a production backend.
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 form definitions 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
- Form definitions — declarative YAML that drives context-dependent UI rendering — sections, fields, visibility conditions, and annotations — so the frontend doesn't hardcode domain-specific logic
- 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 |
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 — Form definitions and context-dependent UI
- 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
- Commands — All available npm scripts
- Project Structure — File layout and conventions
- Troubleshooting — Common issues and solutions
Node.js >= 20.19.0