| name | patterns-entity-modeling |
| description | This skill MUST be invoked when the user says "extract entities", "define data model", "model relationships", "entity modeling", or "domain model". SHOULD also invoke when user mentions "relationship", "cardinality", "state machine", or "data attributes". |
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
| 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):
| 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:
| 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:
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)
