Modeling Domain Entities

Overview

Extract and model domain entities from requirements using Domain-Driven Design principles. This skill covers entity identification, attribute definition, relationship modeling, and state machine documentation.

When to Use

• Creating data-model.md from requirements or specifications

• Extracting entities from user stories and functional requirements

• Defining attributes, types, and constraints for entities

• Modeling relationships between entities with cardinality

• Documenting state machines for stateful entities

• Brownfield analysis of existing data models

When NOT to Use

• API contract design - Use humaninloop:patterns-api-contracts instead

• Database schema migration - This skill is conceptual, not implementation

• When data model already exists and is complete - Don't duplicate work

• Pure validation rules - Model entities first, then add validation

• Technical architecture decisions - Use humaninloop:patterns-technical-decisions

Entity Extraction

Identification Heuristics

Look for entities in:

Source Pattern Example

User stories "As a [Role]..." User, Admin, Guest

Subjects "The [Entity] must..." Task, Order, Product

Actions "...create a [Entity]" Comment, Message, Report

Possessives "[Entity]'s [attribute]" User's profile, Order's items

Status mentions "[Entity] status" TaskStatus, OrderState

Entity vs. Attribute Decision

IF concept has its own lifecycle → Entity IF concept only exists within another → Attribute IF concept connects two entities → Relationship (possibly join entity) IF concept has just one value → Attribute

Examples:

• "user email" → Attribute of User (just one value)
• "user address" → Could be Entity (if reused) or Attribute (if embedded)
• "order items" → Separate entity (has own lifecycle)
• "task status" → Enum/attribute (limited values)

Brownfield Entity Status

When modeling in brownfield projects:

Status Meaning Action

[NEW]

Entity doesn't exist Create full definition

[EXTENDS EXISTING]

Adding to existing entity Document new fields only

[REUSES EXISTING]

Using existing as-is Reference only

[RENAMED]

Avoiding collision Document new name + reason

Attribute Definition

Standard Attributes

Every entity typically needs:

Field Type Required Description

id Identifier Yes Primary key

createdAt Timestamp Yes Creation time

updatedAt Timestamp Yes Last modification

deletedAt Timestamp No Soft delete marker

Attribute Format

Conceptual Types

Use conceptual types (not database-specific):

Conceptual Type Description

Identifier / UUID

Unique identifier

Text / Text(N)

String with optional max length

Email

Email format string

URL

URL format string

Integer

Whole number

Decimal / Decimal(P,S)

Decimal with precision

Boolean

True/false

Timestamp

Date and time

Date

Date only

Enum[values]

Fixed set of values

JSON

Structured data

Reference(Entity)

Foreign key reference

PII Identification

Mark sensitive fields:

Relationship Modeling

Relationships connect entities with defined cardinality: One-to-One (1:1), One-to-Many (1:N), or Many-to-Many (N:M).

See RELATIONSHIP-PATTERNS.md for detailed patterns, join entity examples, and documentation formats.

Relationship Diagram (Text)

Entity Relationships

User ──1:N──▶ Task (owns) User ──1:N──▶ Session (has) User ◀──N:M──▶ Project (via ProjectMember) Task ──N:1──▶ Project (belongs to)

State Machine Modeling

Entities with status fields need state transition documentation.

See STATE-MACHINES.md for patterns, diagram formats, and common workflows.

When to Model State

Model state machines when:

• Entity has a status or state field

• Requirements mention workflow or lifecycle

• Specific actions change entity state

• Certain actions only valid in certain states

Validation Rules

Constraints and validation rules ensure data integrity.

See VALIDATION-RULES.md for constraint patterns, format validations, and business rule documentation.

data-model.md Structure

Data Model: {feature_id}

Entity definitions and relationships for the feature. Generated by Domain Architect.

Summary

Entity: User [EXTENDS EXISTING]

Existing entity extended with authentication fields.

Attributes

Existing Attributes (Not Modified)

Entity: Session [NEW]

User authentication session.

Attributes

Relationships

Relationships

[Relationship documentation]

State Machines

[State machine documentation if applicable]

Traceability

Quality Checklist

Before finalizing entity model, verify:

• Every noun from requirements evaluated for entity status

• Each entity has id, createdAt, updatedAt fields

• All attributes have type, required flag, description

• Relationships include cardinality and direction

• PII fields marked and documented

• State machines documented for stateful entities

• Brownfield status indicated for each entity

• Traceability to requirements documented

Common Mistakes

Missing Entities

❌ Skipping entities mentioned in requirements ("we'll add that later") ✅ Evaluate every noun from requirements for entity status

Anemic Entities

❌ Entity with only id field and no attributes ✅ Every entity needs meaningful attributes that describe its purpose

Implementation Types

❌ Using VARCHAR(255) , INT(11) , BIGINT in data model ✅ Use conceptual types: Text(100) , Integer , Identifier

Undefined Relationships

❌ Reference attributes without relationship documentation ✅ Every Reference(Entity) needs cardinality and relationship description

Hidden State Machines

❌ Status/state fields without transition documentation ✅ Every status field needs state machine diagram and valid transitions

Unmarked PII

❌ Email, phone, address fields without PII markers ✅ Always mark sensitive data with PII or PII-SENSITIVE

Orphan Entities

❌ Entities with no relationships to other entities ✅ Every entity connects to at least one other entity (or is explicitly standalone)