data-modeling-domain

Data Modeling & Domain

Data models encode business rules. Treat schema, state, and naming decisions as long-lived product contracts.

Domain Modeling

• Use domain language in types, tables, events, and functions. Avoid generic names such as data, item, payload, or status without context.
• Document core invariants: what must always be true, who can change it, and what events change it.
• Model state transitions explicitly. Avoid free-form status values without an allowed transition map.
• Use value objects or narrow types for money, dates, IDs, units, quantities, and other rule-heavy values.

Ownership

• Assign a clear owner for each data model or bounded context.
• Do not let unrelated modules write directly to another context's data without an explicit service, event, or contract.
• Keep derived data traceable to its source of truth.

Schema Design

• Design indexes from real query patterns and cardinality, not guesses.
• Use constraints for invariants the database can enforce.
• Avoid nullable fields unless the meaning of null is explicit.
• Classify sensitive fields at design time and apply encryption, tokenization, retention, and audit rules when needed.

Migrations

• Migrations must be backward-compatible when possible and safe for rolling deploys.
• Separate expand, backfill, switch, and contract phases for risky schema changes.
• Backfills must be resumable, observable, and rate-limited when touching production-scale data.
• Add rollback or forward-fix instructions for every non-trivial migration.