Authoring Domains
The mental model
A domain is a bounded context — a coherent slice of your system where terms have precise, unambiguous meaning. It is not a database schema, not a microservice boundary, and not a module in your codebase. It is a language boundary: inside the domain, everyone agrees on what “Session” or “Bookmark” means.
Think of a domain as the answer to: “What does this part of the system know and do?”
Actions and events first
The most common mistake is starting with a data model. Resist this. Begin with what the system does:
- Actions — commands that change state (“add-bookmark”, “lock-account”)
- Events — facts that happened (“bookmark-added”, “account-locked”)
Only after you have a clear picture of behaviour should you derive the model. The DBML schema emerges from your aggregates; it does not drive them.
Identifying domain boundaries
Use these heuristics to decide if something belongs in one domain or deserves its own:
- Language test: If the same word means different things in two contexts (“Order” in shipping vs. billing), you have two domains.
- Change frequency: Things that change together belong together. If changing the authentication rules never touches bookmarking logic, they are separate.
- Team ownership: If two different teams would naturally own the concepts, split them.
- Event coupling: If domain A emits an event that domain B listens to, they are likely separate. If they share internal state, they might be one domain that needs splitting.
Relationship to features and flows
Domains are lower-level than features. A feature uses a domain’s API; it does not redefine it. Multiple features can share a single domain. Flows reference domain actions as step operations.
The cross-reference works like this:
- A feature declares
domains="domain/auth"to state its dependency - A flow step uses
action="login"which must be declared in some domain’s API
Structuring domain content
Glossary
Define terms when they are ambiguous, overloaded, or specific to your bounded context. Skip obvious terms — a glossary is not a dictionary. Every term should pass the test: “Would a new team member misunderstand this without a definition?”
Model (DBML)
Derive your model from aggregates. Each table note should name the aggregate it belongs to and the commands it handles. Use the model to communicate storage shape, not to design it up-front.
API (actions, operations, events, errors)
- Actions are fire-and-forget commands (no return value)
- Operations are request/response (return a value, can throw errors)
- Events are facts broadcast after state changes
- Errors are named failure modes with codes
Policies
Policies express reactive rules: “When X happens, automatically do Y.” They capture business logic that runs without user intervention. Example: “When login fails three times, lock the account.”
Common mistakes
| Mistake | Why it hurts |
|---|---|
| UI concerns in domains | Domains model business logic, not presentation. “Show a toast” is a feature/surface concern. |
| Skipping events | Without events, other domains cannot react. Events are the integration contract. |
| Premature model | Designing tables before understanding behaviour leads to CRUD-driven specs that miss the point. |
| One giant domain | If your domain has 15+ actions, it likely contains multiple bounded contexts. Split it. |
| Duplicating feature API | The domain owns the canonical API. Features reference it; they do not redeclare the same actions. |
Evolution
Domains grow as you discover new behaviour. Add actions and events freely. Be cautious about renaming — other documents reference your API by name. When a domain becomes unwieldy, extract a sub-domain and update cross-references.