Safety Net Blueprint

A systems integration blueprint for safety net benefits programs, built on a reusable contract-driven development framework. 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.

Stability: All packages are at 0.x — minor versions may include breaking changes until 1.0.0 is declared. Pin your versions if stability matters.

New here? Browse all diagrams and reference tools in the Explorer hub.

This repository has two layers:

• The Blueprint Framework — domain-agnostic tooling for contract-driven API development: overlay resolution, validation, state machine engine, mock server, client generation, and explorer. The framework packages (blueprint-core, blueprint-cli, blueprint-mock-server, blueprint-explorer) can be used independently to build contract-driven systems for any domain.
• The Safety Net Contracts — the reference implementation of the framework for safety net benefits programs: OpenAPI specs, state machines, annotations, and overlays across a dozen domains.

Together they provide:

• Base contract artifacts — OpenAPI specs, state machine definitions, metrics, and field metadata that define both data operations (REST) and behavioral operations (RPC)
• 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, field-level permissions, and multilingual labels as contract artifacts served by the backend
• Client generation — typed TypeScript SDK from resolved specs
• State overlays — states customize contracts without forking the base files

The monorepo separates domain-agnostic framework tooling from safety-net-specific contracts:

blueprint-core and blueprint-cli are domain-agnostic — they can be used for any contract-driven project. safety-net-contracts depends on blueprint-cli and uses blueprint-core as its framework.

At the core of the blueprint is a domain-agnostic framework (blueprint-core) that implements the architectural patterns — contract-first API design, overlay-based customization, state machine-driven behavior, event-driven integration — as reusable tooling. The safety net contracts package applies these patterns to the safety net benefits domain. Other domains could use the same framework to build their own contract-driven systems.

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.

Using the framework to define a new contract-driven API domain — whether extending safety net or building something in the same space? Start here: Building a New Domain

npm install

# Start mock server + Swagger UI
npm run mock:start:all

Visit http://localhost:3000 for interactive API docs.

After cloning, run the one-time setup to install the pre-push git hook:

npm run setup:hooks

This 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.

If your change affects a published package, include a changeset before opening a PR. See CONTRIBUTING.md for guidance on writing changeset descriptions and how the release process works.

Full command reference →

• Contract-Driven Architecture — Contract artifacts, portability, adapter pattern
• Domain Design — Domain organization, entities, data flow
• API Architecture — API organization, operational concerns

• 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

• Safety Net Contracts
• Mock Server

Node.js >= 22.11.0

PolyForm Noncommercial License 1.0.0