---

name: patterns-entity-modeling description: This skill should be used when the user asks to "extract entities", "define data model", "model relationships", or mentions "entity", "data model", "relationship", "cardinality", "domain model", or "state machine". Provides DDD-style entity modeling including attributes, relationships, and state machines.

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

CopyIF 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

Copy| 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:

Copy| 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)

Copy## Entity Relationships

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

Copy

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

Copy# 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