The DDD Book

Domain-Driven Design in jinflow — the discipline, and the decisions.

---

What DDD is

In 2003 Eric Evans gave a name to something good software teams had always done but rarely admitted: Domain-Driven Design — the unglamorous, essential work of taking the domain’s language seriously. Not the database’s language, not the framework’s — the language the people who live in the problem actually speak. The model is not a diagram you draw once; it is the shared vocabulary, kept honest by code that uses the same words.

“The heart of software is its ability to solve domain-related problems for its user.” — Eric Evans

DDD is cartography for meaning. You draw bounded contexts — regions inside which a word means exactly one thing — and you refuse to let a word leak across a boundary carrying the wrong meaning. Between contexts you build explicit bridges: a published language others may consume, an anti-corruption layer where a foreign system’s vocabulary is translated at the border instead of seeping in. Inside a context you find the aggregates — the clusters of state that change together, guarded by one root — and you record what happened as domain events, named in the domain’s own words.

The principles

A short, working list — the ones this book leans on:

1. The language is the model. If the team says Verdict and the code says assessment_row, one of them is lying.
2. A boundary is a promise. Inside a bounded context a term has one meaning; crossing the border is an explicit, translated act.
3. Translate at the edge, never in the middle. Foreign vocabularies are handled by an anti-corruption layer at the boundary, so the core model stays clean.
4. Aggregates guard their own consistency. State that changes together lives together, behind one root, with one identity.
5. What happened is a first-class fact. Domain events carry the domain’s words for its own history.
6. The map is drawn deliberately. Context relationships (who conforms to whom, who publishes what) are decisions, not accidents.

How the principles live in jinflow

jinflow didn’t set out to be a DDD system and then discover these principles. It grew up around the same convictions, and they line up almost one-to-one:

DDD principle	In jinflow
The language is the model	The analytical vocabulary — Signal, Perspective, Thesis, Verdict, Subject Matter, Dossier, Run — is the product. Renames are governance acts with recorded history.
A boundary is a promise	Tenant isolation: each tenant is a bounded context with its own AFS, its own KLS, its own schema. No cross-tenant data layer exists — by design, not omission.
Translate at the edge	Bronze source-system dispatch is a textbook anti-corruption layer: OPALE, SAP, Navision vocabularies are translated to the canonical schema in Bronze, and nowhere else. From Silver onward the model is source-agnostic.
Published language	Gold is the product contract. Signals read Gold entities by contract name (BillingEvent, not gold_billing_events). The KLS is the tenant’s published language, self-describing down to its AFS archive.
Aggregates guard consistency	The Run (Sense 56): one root (run_id), one manifest, an append-only event stream, idempotent terminal state. The KLS snapshot: immutable once stamped.
Domain events	The Broadcast (Sense 55) is literally CloudEvents — run.started, run.node.finished, run.error — the domain narrating its own history in its own words.
The map is drawn deliberately	Sense 62 (The Fleet): “a facet classifies, never connects; connection is an explicit instance-to-instance API — the API is the membrane.” That sentence is a context map.

The vocabularies

jinflow deliberately fosters four vocabularies, each a bounded context of meaning with its own owner and its own rate of change:

Vocabulary	Owner	Examples	Changes when
Platform	The engine	Signal, Thesis, Verdict, Run, KLS, AFS, Perspective	A Sense lands
Pack	The domain pack	Material, Case, Cost Center (nuMetrix); Parcelle, Cuvée (Millésime)	Domain expertise deepens
Tenant	The tenant	Local overrides via display.nav_labels, entity YAML labels, tenant glossary	The customer speaks
Standards	The Codex (Sense 53)	UCUM, ISO 8601, ISO 4217, WGS 84	The outside world rules

Two disciplines keep them honest:

• The two-layer language policy. Display language evolves freely (SMEbit → Subject Matter, BitBundle → Dossier); identifier language is frozen (smebit_*, bb_* slugs live on in YAML, tables, contracts). Evans would call the lag a smell; jinflow made it a policy — and it has held. The corollary: every new vocabulary must declare, on arrival, which of its words are display-tier and which are identifier-tier. (The Typology’s seven kinds are identifier-tier; their explanations are display-tier.)
• Pack ≠ tenant, watched closely. The pack seeds, the tenant owns. A pack term inherited unchanged is still spoken by the tenant — the cascade (Sense 43) resolves whose voice you hear, and the boundary deserves the same explicitness the platform/pack boundary already has.
• Foreign names never surface (ruled by Mig, 2026-07-17). Implementation vocabulary — web APIs, library classes, protocol names — belongs to someone else’s bounded context and stays at the boundary, behind a wrapper that speaks jinflow (the same anti-corruption move Bronze applies to SAP’s column names). The founding example: Sense 63’s transport is the browser’s BroadcastChannel, which near-collides with Sense 55 (The Broadcast, the run event stream); if it ever surfaces, the jinflow-side name is SatelliteChannel — named for what it is for, not how it moves.

The open frontier here is making the vocabularies visible: Chapter 02 — The Marked Language — every term in the UI marked with its bounded context, hover for the term’s passport.

How to read this book

Each chapter after this one is a decision — a real modeling question pulled from real work, argued through the DDD lens, resolved (or honestly left open), and where resolved, shipped. They’re not theory. They’re field notes from drawing boundaries.

• Chapter 01 — The Verb and the Run — what it means to be a Verb; why every state-changing Verb must leave a Run. Resolved + shipped.
• Chapter 02 — The Marked Language — marking every UI term with its bounded context; the hover passport. Phases 1–3 shipped (marks, semantic bindings, provenance, nav, legend, the vocabulary lint); prose marking and search remain.
• Chapter 03 — The Compare Exception — the suspected membrane hole, investigated: the shipped Compare is time-travel inside one tenant (acquitted), and the chapter leaves behind the four rules for cross-tenant comparison when it truly arrives. Resolved.

Started by the Console sister, 2026-07-17. Chapters welcome from every desk.