Domain Model and Aggregates¶

This document defines the key aggregate roots, entities, and value objects for the Employment Services SaaS domain. It is written for architects and engineers implementing the domain model.

The domain model follows Domain-Driven Design principles, with aggregates encapsulating invariants and business rules. This document provides a concrete model that can be implemented using ConnectSoft's microservice template.

Important

Critical Business Rules: 1. An Engagement must be associated with a Tenant and a Squad 2. A Squad cannot exceed capacity for overlapping engagements 3. Invoices are generated based on engagement terms and work completion 4. Tenant isolation is enforced at the aggregate level 5. All domain operations must maintain data consistency within aggregates

Modeling Principles¶

DDD Alignment¶

Aggregates Encapsulate Invariants - Business rules enforced within aggregates
Use IDs - Use GUIDs/UUIDs rather than natural keys for aggregates
Value Objects - Use value objects for concepts without identity (Money, TimePeriod)
Domain Events - Important state changes emit domain events
Bounded Contexts - Each context has its own domain model

See: Clean Architecture & DDD for architecture principles.

Aggregate Design¶

One Aggregate Root - Each aggregate has one root entity
Consistency Boundary - Invariants enforced within aggregate
Event Sourcing - Consider event sourcing for audit-heavy aggregates
Optimistic Concurrency - Use version numbers for concurrency control

Key Aggregates by Context¶

Tenant Management Context¶

Aggregate	Root Entity	Description
Tenant	`Tenant`	Tenant organization with subscription and edition
TenantEditionAssignment	`TenantEditionAssignment`	Edition features assigned to tenant
TenantSettings	`TenantSettings`	Tenant-level configuration and settings

Tenant Aggregate: - TenantId (Guid) - Aggregate root ID - Name (string) - Tenant name - Subscription (Subscription) - Subscription details - Edition (Edition) - Edition assignment - Status (TenantStatus) - Active, Suspended, Cancelled - CreatedAt (DateTime) - Creation timestamp - Settings (TenantSettings) - Tenant settings

Customer Accounts Context¶

Aggregate	Root Entity	Description
CustomerOrganization	`CustomerOrganization`	Customer organization within tenant
Contact	`Contact`	Individual contact within organization

CustomerOrganization Aggregate: - CustomerId (Guid) - Aggregate root ID - TenantId (Guid) - Tenant reference - Name (string) - Organization name - Contacts (List) - Organization contacts - Status (CustomerStatus) - Active, Inactive - CreatedAt (DateTime) - Creation timestamp

Project & Engagement Context¶

Aggregate	Root Entity	Description
Engagement	`Engagement`	Project engagement with squad and contract terms
Project	`Project`	Project definition and metadata
Milestone	`Milestone`	Project milestone and deliverables

Engagement Aggregate: - EngagementId (Guid) - Aggregate root ID - TenantId (Guid) - Tenant reference - CustomerId (Guid) - Customer reference - ProjectId (Guid) - Project reference - SquadId (Guid) - Squad reference - ContractTerms (ContractTerms) - Engagement terms - Status (EngagementStatus) - Draft, Active, Completed, Cancelled - StartDate (DateTime) - Engagement start date - EndDate (DateTime?) - Engagement end date (optional) - CreatedAt (DateTime) - Creation timestamp

Squad & Staffing Context¶

Aggregate	Root Entity	Description
Squad	`Squad`	Squad definition with composition and capacity
Assignment	`Assignment`	Assignment of squad to engagement

Squad Aggregate: - SquadId (Guid) - Aggregate root ID - TenantId (Guid) - Tenant reference - Name (string) - Squad name - Composition (SquadComposition) - Roles and members - Capacity (Capacity) - Available capacity - Status (SquadStatus) - Available, Assigned, Unavailable - CreatedAt (DateTime) - Creation timestamp

Assignment Aggregate: - AssignmentId (Guid) - Aggregate root ID - SquadId (Guid) - Squad reference - EngagementId (Guid) - Engagement reference - StartDate (DateTime) - Assignment start date - EndDate (DateTime?) - Assignment end date - Status (AssignmentStatus) - Active, Completed, Cancelled

Work Management Context¶

Aggregate	Root Entity	Description
Epic	`Epic`	High-level feature or capability
UserStory	`UserStory`	User story with acceptance criteria
Task	`Task`	Individual task or work item
Sprint	`Sprint`	Sprint definition and tracking

Epic Aggregate: - EpicId (Guid) - Aggregate root ID - EngagementId (Guid) - Engagement reference - Title (string) - Epic title - Description (string) - Epic description - Status (EpicStatus) - Backlog, InProgress, Done - UserStories (List) - Associated user stories

Billing & Invoicing Context¶

Aggregate	Root Entity	Description
PricePlan	`PricePlan`	Pricing plan definition
Invoice	`Invoice`	Invoice with line items
Payment	`Payment`	Payment record and status

Invoice Aggregate: - InvoiceId (Guid) - Aggregate root ID - TenantId (Guid) - Tenant reference - CustomerId (Guid) - Customer reference - EngagementId (Guid) - Engagement reference - LineItems (List) - Invoice line items - TotalAmount (Money) - Total invoice amount - Status (InvoiceStatus) - Draft, Issued, Paid, Cancelled - IssueDate (DateTime) - Invoice issue date - DueDate (DateTime) - Payment due date

Important Value Objects¶

Money¶

Purpose: Represent monetary amounts with currency

Properties: - Amount (decimal) - Monetary amount - Currency (string) - Currency code (USD, EUR, etc.)

Invariants: - Amount must be non-negative - Currency must be valid ISO code

TimePeriod¶

Purpose: Represent time periods (start and end dates)

Properties: - StartDate (DateTime) - Period start date - EndDate (DateTime) - Period end date

Invariants: - EndDate must be after StartDate - Period must be valid (not negative duration)

CapacitySlot¶

Purpose: Represent available capacity slot for squad

Properties: - StartDate (DateTime) - Slot start date - EndDate (DateTime) - Slot end date - Capacity (decimal) - Available capacity (0.0 to 1.0)

Invariants: - Capacity must be between 0.0 and 1.0 - EndDate must be after StartDate

RoleDefinition¶

Purpose: Define squad role (Architect, Developer, QA, DevOps, PM)

Properties: - RoleType (RoleType enum) - Role type - Name (string) - Role name - Description (string) - Role description

Invariants: - RoleType must be valid - Name must not be empty

Invariants and Business Rules¶

Tenant Management Rules¶

Tenant Isolation - All operations must be scoped to tenant
Edition Features - Edition features must be valid and available
Subscription Status - Active subscription required for platform access

Project & Engagement Rules¶

Engagement Association - Engagement must be associated with Tenant, Customer, Project, and Squad
Date Validation - Engagement end date must be after start date
Status Transitions - Engagement status transitions must be valid (Draft → Active → Completed)

Squad & Staffing Rules¶

Capacity Constraint - Squad cannot exceed capacity for overlapping engagements
Assignment Validation - Assignment must reference valid Squad and Engagement
Date Overlap - Assignments cannot overlap if squad capacity is exceeded

Billing Rules¶

Invoice Association - Invoice must be associated with Tenant, Customer, and Engagement
Amount Calculation - Invoice amount calculated from engagement terms and work completion
Payment Validation - Payment amount must match invoice amount