domain-modeling

name	domain-modeling
description	Model business domains with entities, relationships, business rules, and permissions. Use when: (1) creating entity definitions, (2) defining business rules (BR-XXX), (3) designing permission structures, (4) analyzing domain impact, (5) maintaining domain documentation.
layer	2
tech_stack	["agnostic","markdown"]
topics	["entity-design","business-rules","relationships","permissions","aggregates","value-objects"]
depends_on	[]
complements	["requirements-engineering"]
keywords	["Entity","Aggregate","ValueObject","BusinessRule","BR-","Relationship","Domain"]

Domain Modeling

Create and maintain business domain models with entities, relationships, business rules, and permission structures.

When to Use

• Creating new entity definitions
• Defining business rules (BR-XXX format)
• Designing permission and role structures
• Analyzing impact of domain changes
• Maintaining docs/domain/ documentation

Entity Definition Template

# {Entity} Entity

> **Aggregate Root**: Yes/No
> **Base Class**: `FullAuditedAggregateRoot<Guid>`
> **Table**: `{Entities}`

## Description
[Purpose of this entity in the domain]

## Properties
| Property | Type | Required | Constraints | Description |
|----------|------|----------|-------------|-------------|
| `Id` | `Guid` | Yes | PK | Unique identifier |
| `Name` | `string` | Yes | MaxLength(100) | Display name |
| `Email` | `string` | Yes | Email format, Unique | Contact email |
| `Status` | `{Entity}Status` | Yes | Enum | Current state |
| `CreatedAt` | `DateTime` | Yes | Auto-set | Creation timestamp |

## Relationships
| Relationship | Type | Target Entity | FK Column | Description |
|--------------|------|---------------|-----------|-------------|
| Parent | N:1 | `{ParentEntity}` | `{Parent}Id` | Belongs to parent |
| Children | 1:N | `{ChildEntity}` | - | Has many children |

## Business Rules
| Rule ID | Rule | Validation Point |
|---------|------|------------------|
| BR-{CAT}-001 | [Rule description] | [When validated] |

## State Transitions

[Initial] → [State1] → [State2] → [Final] ↓ [Cancelled]

## API Access
| Operation | Permission | Roles |
|-----------|------------|-------|
| List | `{Project}.{Entities}` | Admin, User |
| View | `{Project}.{Entities}` | Admin, User |
| Create | `{Project}.{Entities}.Create` | Admin |
| Update | `{Project}.{Entities}.Edit` | Admin |
| Delete | `{Project}.{Entities}.Delete` | Admin |

## Sample Data
| Id | Name | Status |
|----|------|--------|
| `{guid}` | Example 1 | Active |

Business Rule Format

Rule ID Convention

BR-{CATEGORY}-{NUMBER}

Categories:
- PAT: Patient rules
- DOC: Doctor rules
- APT: Appointment rules
- SCH: Schedule rules
- MED: Medical record rules
- SYS: System-wide rules

Rule Documentation

| ID | Rule | Enforcement | Impact |
|----|------|-------------|--------|
| BR-APT-001 | Appointments cannot overlap for same doctor | Create/Update | Reject with error |
| BR-APT-002 | Appointments must be within doctor schedule | Create | Reject with error |
| BR-PAT-001 | Patient email must be unique | Create/Update | Reject with error |

Rule Template (Detailed)

**BR-{CAT}-{NNN}: {Rule Name}**

**Description**: [What the rule enforces]
**Trigger**: [When this rule applies]
**Condition**: [The logic to evaluate]
**Action**: [What happens when condition is met/not met]
**Exception**: [Any exceptions to this rule]
**Related**: [Related rules or entities]

Permission Structure

Naming Convention

{ProjectName}.{Resource}.{Action}

Actions:
- (none) = Default/View
- Create
- Edit
- Delete
- {Custom} = Domain-specific actions

Permission Table Template

## {Resource} Permissions

| Permission | Description | Roles |
|------------|-------------|-------|
| `{Project}.{Resources}` | View {resources} | Admin, Manager, User |
| `{Project}.{Resources}.Create` | Create new {resource} | Admin, Manager |
| `{Project}.{Resources}.Edit` | Modify {resource} | Admin, Manager |
| `{Project}.{Resources}.Delete` | Delete {resource} | Admin |
| `{Project}.{Resources}.{Custom}` | [Custom action] | [Specific roles] |

Role Definition Template

## {Role}

**Description**: [Role purpose and scope]

### Capabilities
- [Capability 1]
- [Capability 2]
- [Capability 3]

### Permissions
| Resource | View | Create | Edit | Delete | Custom |
|----------|------|--------|------|--------|--------|
| Patients | ✓ | ✓ | ✓ | - | - |
| Doctors | ✓ | - | - | - | - |

### Restrictions
- [What this role cannot do]
- [Scope limitations]

Impact Analysis Template

# Impact Analysis: {Feature Name}

## Summary
| Metric | Count |
|--------|-------|
| New Entities | X |
| Modified Entities | Y |
| New Business Rules | Z |
| Modified Business Rules | W |
| New Permissions | N |
| Risk Level | Low/Medium/High |

## Entity Changes

### New Entities
| Entity | Reason | Relationships |
|--------|--------|---------------|
| {Entity} | [Why needed] | [Related to...] |

### Modified Entities
| Entity | Change | Before | After | Reason |
|--------|--------|--------|-------|--------|
| {Entity} | New property | - | `{Prop}: {Type}` | [Why] |
| {Entity} | New relationship | - | `{Nav}: {Target}` | [Why] |

## Business Rule Changes

### New Rules
| ID | Rule | Justification |
|----|------|---------------|
| BR-XXX-001 | [Rule] | [Why needed] |

### Modified Rules
| ID | Before | After | Reason | Risk |
|----|--------|-------|--------|------|
| BR-XXX-001 | [Old rule] | [New rule] | [Why] | Medium |

## Permission Changes
| Permission | Roles | Justification |
|------------|-------|---------------|
| `{Project}.{Resource}.{Action}` | [Roles] | [Why needed] |

## Affected Components
| Component | Impact | Action Required |
|-----------|--------|-----------------|
| `{Entity}AppService` | [Change type] | [Create/Modify] |

## Test Impact
| Existing Test | Impact | Action |
|---------------|--------|--------|
| `{Test}_Tests` | [Breaking/None] | [Update/None] |

## Risks & Concerns
| Concern | Severity | Mitigation |
|---------|----------|------------|
| [Issue] | Low/Medium/High | [How to address] |

## Stakeholder Sign-off Required
- [ ] Product Owner - [What needs approval]
- [ ] Tech Lead - [What needs approval]
- [ ] Security - [What needs approval]

Relationship Patterns

One-to-Many (1:N)

Parent Entity                Child Entity
┌─────────────┐             ┌─────────────┐
│ Doctor      │ 1 ────── N  │ Appointment │
│             │             │ DoctorId    │
└─────────────┘             └─────────────┘

Many-to-Many (M:N via junction)

Entity A                    Junction                    Entity B
┌─────────────┐            ┌─────────────┐            ┌─────────────┐
│ Patient     │ 1 ──── N   │ PatientTag  │ N ──── 1  │ Tag         │
│             │            │ PatientId   │            │             │
│             │            │ TagId       │            │             │
└─────────────┘            └─────────────┘            └─────────────┘

Quality Checklist

Entity Definition

• All properties have type and constraints
• Relationships clearly defined with FK
• Business rules listed with BR-XXX IDs
• API access permissions mapped
• Sample data provided

Business Rules

• Uses BR-{CAT}-{NNN} format
• Enforcement point specified
• Impact of violation documented
• Cross-referenced in entity files

Permissions

• Follows naming convention
• Mapped to appropriate roles
• Custom actions documented

References

• references/entity-examples.md - Real entity examples
• references/rule-patterns.md - Common business rule patterns