domain-modeling

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
```markdown
| 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