domain-modeling

Domain Modeling

Iron Law

ILLEGAL STATES MUST BE UNREPRESENTABLE IN THE DOMAIN CORE.

If the type or data shape permits a state the domain forbids, a future caller will construct it. Make the state impossible to express rather than guarding against it.

When to Use

• Data shape affects correctness: domain data, fields, states, allowed combinations, transitions, validation boundaries, value objects, functional cores, or effect isolation.
• Reviewing code where I/O, mutation, and business rules are coupled.

When NOT to Use

• Public HTTP contract details; use api. Physical schema; use database.
• Module organization, layering, DDD tactical patterns; use architecture.
• Broad refactoring sequence; use refactoring.

Rules

1. Decide data shapes and invariants before writing transformations.
2. Distinguish identity, state, value, and time. Prefer immutable records, sums, and maps. A class that wraps pure functions is a module; avoid classes that bundle behavior with mutable state.
3. Split code into data, calculations, and actions. Maximize data and calculations; minimize actions.
4. Parse external input once, at the boundary, into a trusted internal shape. Internal code never handles raw strings or maps. Use the ecosystem's de-facto schema library (Pydantic in Python, Zod in TypeScript), honoring any existing project choice; hand-roll with the same discipline only where no clear leader exists.
5. Model allowed states as explicit variants, not flag or nullable combinations. Split a nullable that means both "missing" and "not loaded" into named states.
6. Effects (async, exceptions, I/O, clocks, randomness, logging, persistence, mutation, shared state) are contagious. Keep them at the imperative shell so the functional core stays pure. Core tests run without mocks, monkey-patches, databases, network, or global time.
7. Discover abstractions from repeated domain meaning. No generic wrappers, base classes, or helper layers before the data proves they pay.
8. Names carry the model. A method states its role in the domain process: settleInvoice or expireHold, not process, handle, or execute. A suffix like Service or Manager is fine only with a domain word saying what kind.
9. Each non-trivial invariant or transition gets a Proof Contract (claim, data invariant, boundary, check, evidence) via proof.
10. A core model, shared invariant, or state machine future work will bind to is listed for approval before implementation; contract-first owns the approval scope. Disposable or purely local shapes are not gated.
11. Load references/dates.md whenever the diff stores, compares, formats, serializes, or computes on dates or times, and references/money.md whenever it does so on monetary amounts.