data-modeling

Data Modeling

This skill covers the architectural side of data design — how to model a domain so that business rules are enforced by structure, not by discipline.

When to Use

• Designing the domain model for a new service with non-trivial business rules
• Existing code has business logic scattered across services with no clear ownership
• Deciding how to partition a domain into aggregates and services
• Reviewing data structures for consistency, invariant enforcement, and boundary clarity

When NOT to Use

• Simple CRUD with no business rules — a flat table is fine
• Physical schema design (column types, indexes) — use sql-and-database
• API request/response shapes — use api-contract

Core Concepts

Ubiquitous Language

Every concept in the domain model uses the same name as the business uses. If the business calls it a "Document Request" and the code calls it a DocReq, you have two models — and they will diverge.

• Name classes, methods, and variables after the business concept they represent
• When a business concept has no name yet, invent one with the domain experts
• Resist mapping business concepts to generic technical names (Manager, Handler, Processor)

Entities vs Value Objects

Entity — has identity that persists over time. Two entities with identical attributes are still distinct.

class Document {
  constructor(
    readonly id: DocumentId,  // identity
    private title: string,
    private content: string,
  ) {}
}
// Two documents with same title and content are different documents

Value Object — defined entirely by its attributes. Two value objects with identical attributes are interchangeable. Immutable by definition.

class DocumentId {
  constructor(readonly value: string) {
    if (!isUUID(value)) throw new Error('DocumentId must be a UUID');
  }
  equals(other: DocumentId): boolean {
    return this.value === other.value;
  }
}

class Tag {
  constructor(readonly value: string) {
    if (!value.trim()) throw new Error('Tag cannot be empty');
    if (value.length > 50) throw new Error('Tag too long');
  }
}