Architecture & Technical Design · master area
Domain Modelling
Entities, rules, relationships — drawn in the domain's own words, before any database, framework, or class file is opened. The model the code is built on, not the model the framework imposes.
Owners: Tech Lead, Developer Phase it lives in: What We Build (Volume III) The corpus principle this enacts: The code speaks the brief.
Where it lives in the chain
- What We Build · Technical Shaping · ADR — where modelling decisions are recorded
- How We Build · Domain Language and Composition — where the model becomes code
How to do this
A domain model names:
- Entities — the things that have identity.
Exam,Grade,Submission,Teacher. NotForm,Record,Entity. - Value objects — the things that have no identity, only value.
Score,Mark,Comment. Replaceable, comparable by value. - Rules — invariants. "An exam cannot be graded after the deadline." "A submission cannot be both
draftandfinalsimultaneously." The rules go into the entity, not into the controller. - Relationships — "An exam has many submissions; one per student per attempt." The cardinality, the lifecycle.
- Operations — the verbs.
gradeExam,submitForGrading,revokeGrade. The model exposes these, not setters.
What good practice looks like
The model is drawn on a whiteboard with the PO and a Designer in the room before any class file exists. The drawing uses the brief's vocabulary — if Gal says "exam," the entity is Exam. If the PO has to translate when reading the code, the model is in the wrong language.
The model is separate from the schema. The schema is how the model persists, not the model itself. Two different stories that touch the same entity often want the same model; the schema serves both. A team that designs the schema first ends up with a database-shaped domain — and the domain language warps to fit.
Related crafts
- Domain Language in Code — where the model becomes code
- Bounded Context Mapping — where the model's vocabulary changes
- State Machine — the lifecycle inside an entity