Individual domain docs and decision logs explain what was decided, in the technical detail engineers need to build against them. This document explains the handful of design philosophies that recur across all of them — what each one means in practice, and why this blueprint relies on it.

A concern that runs through many of these philosophies is the set of qualities a benefits system needs to remain operable over the long haul: that new consumers and integrations can be added without unpicking what already works, that vendors can be replaced without rewriting the business logic that depended on them, that the system stays comprehensible as the people responsible for it change, that contracts can be tested before any real implementation exists, and that a complete record of every change is always recoverable. Several of the philosophies below are direct responses to that pressure, each from a different angle.

1
Contract-first / spec-first design

A contract in this blueprint says exactly what an implementation needs to do — not roughly, but completely: what a resource looks like, how a workflow moves through its lifecycle, what the business logic is supposed to produce. That completeness means work doesn't have to happen one step at a time, waiting on a real system to exist first. A vendor can build directly from the contract. A mock server can be generated from it. A coding agent can generate an implementation straight from it. And whoever picks up the work next builds from that same precise answer, not a guess reverse-engineered from someone else's code.

A resource's shape, lifecycle states and transitions, decision logic, process sequencing, and data assembly are all written down and agreed on before anyone builds — not written afterward to describe whatever the code happened to do.

2
Domain-Driven Design

A benefits program isn't one undifferentiated thing — intake, eligibility, workflow, and client records are different areas of work, each with its own staff, its own rules, and its own vocabulary. Organizing the system around those same real-world groupings makes it something program staff can recognize and reason about, not just developers. It also keeps the system coherent as it grows: each area stays a self-contained piece with a clear job, instead of every new feature getting piled into one tangled whole.

The blueprint is organized into domains that mirror how the business itself is organized — Intake, Eligibility, Workflow, Client Management, and so on — each owning its own data and rules. The same word can mean two different things in two different domains, on purpose (e.g. Income in both Client Management and Intake). Nothing in the contracts lets one domain reach into another's storage directly — every cross-domain access goes through the owning domain's published interface.

3
Adapters (Ports & Adapters / Hexagonal Architecture)

A state picks a workflow engine, case management platform, or database once — but lives with that choice for years, long after the conditions that made it right can change: pricing, vendor roadmap, support quality, or whether the vendor is still in business. If business logic calls that vendor directly, leaving gets harder every year. The goal is: swap the vendor, not the logic that depends on it.

The core logic never talks to a vendor directly — a separate, replaceable layer does the translation, so a vendor's quirks stay on the vendor's side of the line. That layer must genuinely translate, not just relay concepts under a different name. Where several parts of the system need to talk to the same category of outside service, they go through one shared door instead of each building their own.

4
Event-Driven Architecture

New consumers of information a domain produces show up throughout the life of a benefits system — a new report, a new downstream process, a new integration nobody anticipated when the domain was first built. If adding a consumer means modifying the domain that produces the information, the amount of code that has to change grows with every consumer added, and "what happened" ends up tangled with "what to do about it" in the same place.

A part of the system announces that something happened, with no particular consumer in mind; anything else that cares subscribes and decides independently how to react, with no central coordinator. A complete audit record — who did what, and when — can be built entirely this way, just by listening to what every domain already announces, rather than asking each domain to separately report to an audit system.

5
Overlay-based customization

A state adopting this blueprint starts with a base that already has the common shape of a benefits system built into it. States still need to customize that base for their own programs, rules, and constraints — and the base keeps evolving after they do. If a state customizes by editing the base directly, every future update has to be manually re-applied on top of every change the state already made, by hand, forever, with the two versions drifting further apart every time.

A state's customization is a separate, targeted patch layered on top of an untouched base, combined by a build step into the final result — so upgrading the base means re-applying that patch, not manually redoing every edit. The combined result is validated exactly the same way the base is, so a customization can't quietly produce something broken that nobody notices until the system is live.

6
Prefer established over novel

Every custom solution carries costs an established one doesn't: no existing tooling, no developers who already know it, no external validation that it works at scale, and no guarantee it'll be maintained beyond the team that built it. An established standard already has an ecosystem: tooling, documentation, prior art, and people who've encountered its failure modes before. The question before designing something custom isn't "could I build this?" but "does something that solves this problem already exist and have traction?"

Contract formats use open standards with established tooling ecosystems: OpenAPI for APIs, CloudEvents and AsyncAPI for events, JSON Schema for validation, JSON Merge Patch for overlays. Where no established standard covers a need exactly, the blueprint reaches for the most widely adopted general-purpose option — CEL for expressions rather than a custom DSL. The same preference applies to architectural patterns: hexagonal architecture, DDD, event-driven choreography, and statecharts are used because they're recognized patterns with documented trade-offs.

7
DRY (Don't Repeat Yourself)

The same piece of knowledge — what an income type looks like, what states a workflow task can be in, what threshold qualifies a household for an expense deduction — will be referenced from many places: the API schema, the state machine, the decision rules, the overlay. If each reference carries its own inline copy, those copies will eventually disagree. The problem isn't redundancy in isolation — it's that redundancy creates multiple sources of truth, and when they drift, there's no authority to say which one is right. In a system where the contracts are supposed to be the authoritative answer, silent drift between them defeats the point.

Every shared concept is defined once and referenced everywhere it's needed — never redefined inline in a second place that can silently diverge. State-specific customization is a targeted patch against one canonical base, not a fork that duplicates the entire base. A policy change — a new income type, a threshold update — happens in one place and flows everywhere that references it.

Reference: Hunt & Thomas, The Pragmatic Programmer ("Don't Repeat Yourself")

Go deeper

For the specific software patterns used to realize these principles, see Architecture Patterns in the repository. For the specific decisions made in each domain, see the architecture docs.