domain-modelinglisted

# 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