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:

| 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