Status: Active development — See the roadmap.
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? Browse all diagrams and reference tools in the Explorer hub.
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
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.
To adopt the blueprint, create a repository, install the base packages, apply overlays to customize the contracts for your context, and point the CLIs at the resolved output. See the Setup Guide for the full walkthrough and the Overlay Guide for overlay authoring.
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
# Start mock server + Swagger UI
npm run mock:start:allVisit http://localhost:3000 for interactive API docs.
After cloning, run the one-time setup to install the pre-push git hook:
npm run setup:hooksThis installs a hook that runs before every push. The hook rebuilds explorer outputs and commits them if stale, then runs npm run preflight — which validates specs, runs tests, and runs integration tests. Use git push --no-verify to skip for work-in-progress pushes.
| 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 resolve -- --spec=<spec-dir> --overlay=<overlay-dir> --out=<out-dir> |
Resolve overlays against base specs |
npm run build --workspace=packages/explorer |
Build all explorer reference tools |
node packages/explorer/build.js --resolved=<dir> --clients=<dir> |
Build explorer from state-specific resolved specs |
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
- Setup Guide — Set up a repository with overlays and CI
- Overlay Guide — Customize contracts with overlays
- Creating APIs — Design new API specifications
- 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