patterns-entity-modeling

Modeling Domain Entities

Purpose

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.

Entity Extraction

Identification Heuristics

Look for entities in:

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:

Attribute Definition

Standard Attributes

Every entity typically needs:

Attribute Format

| Attribute | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| id | UUID | Yes | auto-generated | Unique identifier |
| email | Email | Yes | - | User's email address |
| name | Text(100) | No | null | Display name |
| role | Enum[admin,member,guest] | Yes | member | Access level |
| isVerified | Boolean | Yes | false | Email verified flag |

Conceptual Types

Use conceptual types (not database-specific):

PII Identification

Mark sensitive fields:

| Attribute | Type | Required | PII | Description |
|-----------|------|----------|-----|-------------|
| email | Email | Yes | **PII** | User's email |
| phone | Text(20) | No | **PII** | Phone number |
| ssn | Text(11) | No | **PII-SENSITIVE** | Social security |

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 | Attributes | Relationships | Status |
|--------|------------|---------------|--------|
| User | 8 | 3 | [EXTENDS EXISTING] |
| Session | 5 | 1 | [NEW] |
| ...

---

## Entity: User [EXTENDS EXISTING]

> Existing entity extended with authentication fields.

### Attributes

| Attribute | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| passwordHash | Text | Yes | - | Hashed password |
| lastLoginAt | Timestamp | No | null | Last login time |

### Existing Attributes (Not Modified)

| Attribute | Type | Description |
|-----------|------|-------------|
| id | UUID | Existing primary key |
| email | Email | Existing email field |

---

## Entity: Session [NEW]

> User authentication session.

### Attributes

| Attribute | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| id | UUID | Yes | auto | Session identifier |
| userId | Reference(User) | Yes | - | Owning user |
| token | Text(255) | Yes | - | Session token |
| expiresAt | Timestamp | Yes | - | Expiration time |
| createdAt | Timestamp | Yes | auto | Creation time |

### Relationships

| Relationship | Type | Target | Description |
|--------------|------|--------|-------------|
| user | N:1 | User | Session belongs to user |

---

## Relationships

[Relationship documentation]

---

## State Machines

[State machine documentation if applicable]

---

## Traceability

| Entity | Source Requirements |
|--------|---------------------|
| User | FR-001, FR-002, US#1 |
| Session | FR-003, US#2 |

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

Anti-Patterns to Avoid

• Missing entities: Don't skip entities mentioned in requirements
• Anemic entities: Entities with only ID are suspicious
• Implementation types: Use conceptual types, not VARCHAR(255)
• Undefined relationships: Every reference needs relationship docs
• Hidden state: Status fields need state machine documentation
• Unmarked PII: Always identify sensitive data
• Orphan entities: Every entity needs at least one relationship