Skip to content

Aggregates & Entities - Audit Trail Platform (ATP)

Domain model with integrity — ATP aggregates enforce business invariants, ensure consistency boundaries, and provide tamper-evident audit trails through immutable event streams.

📋 Documentation Generation Plan

This document will be generated in 8 cycles. Current progress:

Cycle Topics Estimated Lines Status
Cycle 1 DDD Fundamentals & ATP Domain Overview (1-2) ~3,000 ⏳ Not Started
Cycle 2 Core Aggregates: AuditEvent & EventStream (3-4) ~3,500 ⏳ Not Started
Cycle 3 Tenant & Policy Aggregates (5-6) ~3,000 ⏳ Not Started
Cycle 4 Classification & Retention Entities (7-8) ~2,500 ⏳ Not Started
Cycle 5 Value Objects & Domain Services (9-10) ~2,500 ⏳ Not Started
Cycle 6 Invariants & Business Rules (11-12) ~3,000 ⏳ Not Started
Cycle 7 Event Sourcing & Persistence (13-14) ~3,000 ⏳ Not Started
Cycle 8 Integration & Bounded Contexts (15-16) ~2,500 ⏳ Not Started

Total Estimated Lines: ~23,000

Purpose & Scope

This document defines the domain model for the ConnectSoft Audit Trail Platform (ATP) using Domain-Driven Design (DDD) principles, establishing the aggregates, entities, value objects, and domain services that form the core business logic and ensure data integrity, consistency, and compliance across all ATP operations.

Key Domain Modeling Principles - Domain-Driven Design (DDD): Aggregates as consistency boundaries, ubiquitous language, bounded contexts - Event-Driven Architecture (EDA): Domain events, event sourcing, CQRS patterns - Immutability: Append-only audit events, tamper-evident storage, cryptographic integrity - Multi-Tenancy: Tenant isolation at aggregate level, tenant-specific policies - Compliance: GDPR, HIPAA, SOC 2 compliance encoded in domain rules - Zero-Trust: Every operation validated, no implicit trust, explicit authorization

What this document covers

  • Establish ATP's domain model structure with aggregates, entities, and value objects following DDD tactical patterns
  • Define core aggregates: AuditEvent, EventStream, Tenant, Policy, Classification, Retention, Export
  • Specify entity lifecycles: creation, state transitions, immutability, deletion (soft/hard)
  • Detail value objects: TenantId, EventId, Timestamp, Classification, Hash, Signature
  • Describe domain invariants: business rules enforced at aggregate boundaries
  • Outline domain events: event types, schemas, publishing patterns
  • Document consistency boundaries: aggregate roots, transactional scope, eventual consistency
  • Specify persistence patterns: event sourcing, read models, snapshots, projections
  • Detail bounded contexts: ingestion, query, policy, export, and their integration contracts
  • Describe domain services: cross-aggregate operations, orchestration, sagas

Out of scope (referenced elsewhere)

Readers & ownership

  • Domain Experts/Product (owners): Domain model design, business rules, invariants, ubiquitous language
  • Backend Developers: Aggregate implementation, entity lifecycle, domain events, persistence
  • Architects: Bounded context design, consistency boundaries, integration patterns, event flows
  • Data Engineers: Read model projections, event sourcing, query optimization, data retention
  • Compliance/Legal: GDPR/HIPAA rules, data classification, retention policies, audit requirements
  • QA/Test Engineers: Domain logic testing, invariant validation, edge case coverage

Artifacts produced

  • Domain Model Diagrams: C4 model, aggregate diagrams, entity relationships, bounded context maps
  • Aggregate Specifications: Per-aggregate documentation with invariants, methods, events
  • Entity Definitions: C# entity classes with annotations, validation, and lifecycle methods
  • Value Object Library: Reusable value objects with equality, validation, and serialization
  • Domain Event Catalog: All domain events with schemas, publishing rules, and consumers
  • Invariant Rules: Business rules encoded as unit tests and runtime validations
  • Persistence Mappings: Entity Framework Core configurations, event store schemas
  • Integration Contracts: Anti-corruption layers, shared kernel, context maps
  • Ubiquitous Language Glossary: Domain terminology, synonyms, and definitions
  • Domain Test Suites: Unit tests for aggregates, integration tests for sagas

Acceptance (done when)

  • All core aggregates (AuditEvent, EventStream, Tenant, Policy, Classification, Retention, Export) are documented with complete specifications
  • Entity lifecycles are defined with state diagrams, transitions, and invariants
  • Value objects are cataloged with creation rules, validation, and immutability guarantees
  • Domain invariants are documented as executable specifications (unit tests) and runtime guards
  • Domain events are cataloged with schemas, publishing patterns, and consumer documentation
  • Consistency boundaries are clearly defined with transactional scope and eventual consistency patterns
  • Bounded contexts are mapped with integration points, shared kernel, and anti-corruption layers
  • Event sourcing patterns are documented with event store schema, snapshots, and projections
  • Persistence mappings are complete for all aggregates with EF Core configurations
  • Code examples include aggregate implementations, domain services, and event handlers
  • Documentation complete with comprehensive examples, diagrams, cross-references, and test coverage

Detailed Cycle Plan

CYCLE 1: DDD Fundamentals & ATP Domain Overview (~3,000 lines)

Topic 1: Domain-Driven Design Fundamentals

What will be covered:

  • Domain-Driven Design (DDD) Overview
  • What is DDD and why ATP uses it
  • Strategic vs tactical patterns
  • Ubiquitous language importance
  • Model-driven design principles

  • DDD in event-driven architectures

  • Building Blocks of DDD (Tactical Patterns)

  • Entities: Objects with identity and lifecycle
  • Value Objects: Immutable objects without identity
  • Aggregates: Consistency boundaries with root entities
  • Domain Events: Things that happened in the domain
  • Repositories: Persistence abstraction for aggregates
  • Domain Services: Operations that don't belong to entities
  • Factories: Complex object creation

  • Specifications: Business rule encapsulation

  • Aggregates Deep Dive

  • What is an aggregate?
  • Aggregate root responsibilities
  • Consistency boundaries
  • Transactional scope (one aggregate per transaction)
  • Aggregate size considerations
  • Identity and lifecycle

  • Invariant enforcement

  • Entities vs Value Objects

  • Entity characteristics (identity, mutability, lifecycle)
  • Value object characteristics (no identity, immutability, replaceability)
  • When to use entities vs value objects
  • Entity equality (by ID)

  • Value object equality (by value)

  • Domain Events

  • What are domain events?
  • Event naming conventions (past tense)
  • Event schemas and versioning
  • Publishing domain events
  • Event handlers and side effects

  • Event sourcing with domain events

  • Bounded Contexts

  • What is a bounded context?
  • Context mapping patterns
  • Shared kernel
  • Anti-corruption layer
  • Published language

  • Customer/supplier relationships

  • Ubiquitous Language

  • Importance in ATP
  • Language evolution
  • Glossary maintenance
  • Code reflects language
  • Documentation uses language

Code Examples: - Entity base class with identity - Value object base class with equality - Aggregate root base class - Domain event base class - Example aggregate with invariants - Repository interface - Domain service example

Diagrams: - DDD building blocks overview - Aggregate structure - Entity vs value object comparison - Domain event flow - Bounded context map

Deliverables: - DDD fundamentals guide - Aggregate design patterns - Entity and value object templates - Domain event framework - Bounded context mapping

Topic 2: ATP Domain Model Overview

What will be covered:

  • ATP Domain Model Philosophy
  • Immutability and tamper-evidence
  • Event-driven core
  • Multi-tenant isolation
  • Compliance by design

  • Zero-trust security model

  • Core Domain Concepts

  • Audit Event: The central concept - a record of something that happened
  • Event Stream: Ordered sequence of audit events for a subject
  • Tenant: Multi-tenant isolation boundary
  • Policy: Rules for classification, retention, access
  • Classification: Data sensitivity and handling requirements
  • Retention: Legal hold and deletion rules

  • Export: eDiscovery and compliance reporting

  • Bounded Contexts in ATP

  • Ingestion Context: Receiving and validating audit events
  • Storage Context: Append-only event store with integrity
  • Classification Context: Auto-classification and PII detection
  • Query Context: Read models and search indexes
  • Policy Context: Tenant policies and compliance rules
  • Export Context: Legal hold, eDiscovery, SIEM integration

  • Integrity Context: Hash chains and signature verification

  • Context Map

  • Upstream/downstream relationships
  • Shared kernel (common value objects)
  • Anti-corruption layers at boundaries
  • Published language (event contracts)

  • Integration patterns (events, commands, queries)

  • Aggregate Catalog

  • AuditEvent Aggregate: Core immutable audit event
  • EventStream Aggregate: Ordered stream with hash chain
  • Tenant Aggregate: Tenant configuration and policies
  • Policy Aggregate: Classification and retention rules
  • ClassificationRule Aggregate: Auto-classification logic
  • RetentionPolicy Aggregate: Data lifecycle management
  • ExportRequest Aggregate: Export and eDiscovery

  • IntegrityProof Aggregate: Cryptographic verification

  • Domain Event Catalog

  • AuditEventReceived: New event ingested
  • AuditEventClassified: Classification applied
  • AuditEventRetained: Retention policy applied
  • EventStreamSealed: Stream made immutable
  • TenantOnboarded: New tenant created
  • PolicyUpdated: Policy configuration changed
  • ExportRequested: Export initiated

  • IntegrityVerified: Hash chain validated

  • Entity Relationships

  • Tenant → Policies (1:N)
  • Tenant → EventStreams (1:N)
  • EventStream → AuditEvents (1:N)
  • Policy → ClassificationRules (1:N)
  • Policy → RetentionPolicies (1:N)
  • AuditEvent → Classification (1:1)

  • AuditEvent → IntegrityProof (1:1)

  • Value Objects Catalog

  • TenantId: Unique tenant identifier (GUID)
  • EventId: Unique event identifier (ULID)
  • StreamId: Event stream identifier
  • Timestamp: Immutable point in time (UTC)
  • Classification: Data sensitivity level
  • Hash: Cryptographic hash (SHA-256)
  • Signature: Digital signature (RSA/ECDSA)
  • Actor: Who performed the action
  • Resource: What was affected

  • Action: What happened

  • Consistency Boundaries

  • Single aggregate per transaction
  • Eventual consistency across aggregates
  • Event-driven communication between contexts
  • Idempotency for at-least-once processing
  • Optimistic concurrency control

Code Examples: - ATP domain model namespace structure - Core aggregate roots (skeleton) - Domain event hierarchy - Value object examples - Context map C# classes - Repository interfaces

Diagrams: - ATP domain model overview (C4 level 2) - Bounded context map - Aggregate relationships - Entity relationship diagram - Domain event flow - Consistency boundaries

Deliverables: - ATP domain model specification - Bounded context documentation - Aggregate catalog - Domain event catalog - Value object library - Context mapping guide

CYCLE 2: Core Aggregates - AuditEvent & EventStream (~3,500 lines)

Topic 3: AuditEvent Aggregate

What will be covered:

  • AuditEvent Aggregate Design
  • Aggregate root: AuditEvent
  • Immutability (created once, never modified)
  • Identity: EventId (ULID for time-ordering)
  • Lifecycle: Created → Classified → Retained

  • No deletion (soft delete with tombstone)

  • AuditEvent Properties

  • Metadata: TenantId, EventId, Timestamp, CorrelationId
  • Actor: Who performed the action (User, Service, System)
  • Action: What was done (Created, Updated, Deleted, Accessed)
  • Resource: What was affected (entity type, ID, name)
  • Context: Additional contextual information
  • Payload: Event data (JSON, encrypted if sensitive)
  • Classification: Data sensitivity level
  • Retention: Retention period and policy

  • Integrity: Hash, signature, previous event reference

  • AuditEvent Creation

  • Factory method: AuditEvent.Create(...)
  • Input validation and sanitization
  • Automatic timestamp assignment (server-side)
  • EventId generation (ULID)
  • Initial classification (default or inferred)
  • Hash calculation

  • Domain event: AuditEventReceived

  • AuditEvent Classification

  • Classify(Classification) method
  • Immutable operation (creates new version)
  • Classification rules application
  • PII detection and redaction

  • Domain event: AuditEventClassified

  • AuditEvent Retention

  • ApplyRetention(RetentionPolicy) method
  • Retention period calculation
  • Legal hold handling
  • Tombstone creation (soft delete)

  • Domain event: AuditEventRetained

  • Invariants

  • EventId must be unique per tenant
  • Timestamp cannot be in the future
  • Actor must be specified
  • Resource must be specified
  • Classification cannot be downgraded (only upgraded)

  • Once tombstoned, cannot be restored

  • Domain Events

  • AuditEventReceived: Event ingested successfully
  • AuditEventClassified: Classification applied
  • AuditEventRetained: Retention policy applied
  • AuditEventTombstoned: Soft deleted

  • AuditEventVerified: Integrity verified

  • Persistence

  • Append-only event store
  • Immutable storage (WORM)
  • Event sourcing (events as source of truth)
  • Snapshots for query optimization
  • Projections for read models

Code Examples: - Complete AuditEvent aggregate class - Factory methods - Invariant validation - Domain event publishing - Entity Framework Core configuration - Unit tests for invariants

Diagrams: - AuditEvent aggregate structure - State transitions - Creation workflow - Classification workflow - Persistence mapping

Deliverables: - AuditEvent aggregate specification - C# implementation - Unit test suite - EF Core mapping - Domain event schemas

Topic 4: EventStream Aggregate

What will be covered:

  • EventStream Aggregate Design
  • Aggregate root: EventStream
  • Ordered sequence of AuditEvents
  • Hash chain for tamper-evidence
  • Identity: StreamId (tenant + subject + stream type)

  • Lifecycle: Open → Sealed → Archived

  • EventStream Properties

  • Metadata: TenantId, StreamId, CreatedAt, SealedAt
  • Subject: What the stream is about (user, resource, transaction)
  • StreamType: Category (user activity, system events, audit trail)
  • Events: Ordered collection of AuditEvents
  • HashChain: Merkle tree or linked hashes
  • Status: Open (accepting events), Sealed (immutable), Archived (cold storage)

  • Statistics: Event count, first/last event timestamps

  • EventStream Creation

  • Factory method: EventStream.Create(tenantId, subject, streamType)
  • Initial state: Open
  • First event establishes stream

  • Domain event: EventStreamCreated

  • Adding Events to Stream

  • AddEvent(AuditEvent) method
  • Validates stream is Open
  • Appends event to ordered list
  • Updates hash chain
  • Increments event count

  • Domain event: EventAddedToStream

  • Sealing Event Stream

  • Seal() method
  • Changes status to Sealed
  • No more events can be added
  • Finalizes hash chain
  • Generates integrity proof

  • Domain event: EventStreamSealed

  • Hash Chain Implementation

  • Each event references previous event hash
  • Stream hash is Merkle root
  • Tamper-evidence: any change breaks chain
  • Verification algorithm

  • Performance optimization (batch hashing)

  • Invariants

  • Events must be added in order
  • Once sealed, no more events
  • Hash chain must be valid
  • All events must belong to same tenant
  • All events must belong to same subject

  • Stream cannot be unsealed

  • Domain Events

  • EventStreamCreated: New stream initialized
  • EventAddedToStream: Event appended
  • EventStreamSealed: Stream finalized
  • EventStreamArchived: Moved to cold storage

  • HashChainValidated: Integrity verified

  • Persistence

  • Stream metadata in relational DB
  • Events in append-only store
  • Hash chain in separate table
  • Archival to Azure Blob (immutable)
  • Snapshot for large streams

Code Examples: - Complete EventStream aggregate class - Hash chain calculation - Seal operation - Integrity verification - EF Core configuration - Unit tests

Diagrams: - EventStream aggregate structure - Hash chain visualization - State machine (Open → Sealed → Archived) - Integrity verification flow - Persistence mapping

Deliverables: - EventStream aggregate specification - C# implementation with hash chain - Integrity verification algorithm - Unit test suite - EF Core mapping

CYCLE 3: Tenant & Policy Aggregates (~3,000 lines)

Topic 5: Tenant Aggregate

What will be covered:

  • Tenant Aggregate Design
  • Tenant Properties
  • Tenant Creation (Onboarding)
  • Tenant Configuration
  • Tenant Policies Association
  • Tenant Suspension/Deactivation
  • Multi-Tenancy Isolation
  • Invariants
  • Domain Events
  • Persistence

Detailed specification similar to Cycle 2

Topic 6: Policy Aggregate

What will be covered:

  • Policy Aggregate Design
  • Policy Types (Classification, Retention, Access)
  • Policy Rules Engine
  • Policy Application
  • Policy Versioning
  • Policy Inheritance
  • Invariants
  • Domain Events
  • Persistence

CYCLE 4: Classification & Retention Entities (~2,500 lines)

Topic 7: Classification Entities

What will be covered:

  • Classification Entity Design
  • Classification Levels
  • Auto-Classification Rules
  • PII Detection Integration
  • Classification Upgrading
  • Compliance Mappings (GDPR, HIPAA)
  • Invariants
  • Domain Events

Topic 8: Retention Entities

What will be covered:

  • RetentionPolicy Entity Design
  • Retention Periods
  • Legal Hold Handling
  • Deletion Rules (Hard vs Soft)
  • Tombstone Pattern
  • GDPR Right to Be Forgotten
  • Invariants
  • Domain Events

CYCLE 5: Value Objects & Domain Services (~2,500 lines)

Topic 9: Value Objects Library

What will be covered:

  • Value Object Design Principles
  • Core Value Objects:
  • TenantId, EventId, StreamId
  • Timestamp, TimeRange
  • Classification, Sensitivity
  • Hash, Signature
  • Actor, Resource, Action
  • CorrelationId, CausationId
  • Value Object Equality
  • Immutability Patterns
  • Validation and Creation
  • Serialization

Topic 10: Domain Services

What will be covered:

  • Domain Service Patterns
  • Cross-Aggregate Operations
  • Integrity Verification Service
  • Classification Service
  • Retention Service
  • Export Service
  • Event Ordering Service
  • Saga Orchestration

CYCLE 6: Invariants & Business Rules (~3,000 lines)

Topic 11: Aggregate Invariants

What will be covered:

  • Invariant Definition and Purpose
  • Per-Aggregate Invariants (detailed for each)
  • Invariant Enforcement (Runtime Guards)
  • Invariant Testing (Unit Tests)
  • Violation Handling
  • Invariant Documentation

Topic 12: Business Rules Engine

What will be covered:

  • Business Rules vs Invariants
  • Rule Definition Language
  • Rule Evaluation Engine
  • Policy Rule Application
  • Rule Versioning
  • Rule Testing Framework

CYCLE 7: Event Sourcing & Persistence (~3,000 lines)

Topic 13: Event Sourcing Patterns

What will be covered:

  • Event Sourcing Fundamentals
  • Event Store Design
  • Event Streams and Subscriptions
  • Snapshots for Performance
  • Projections and Read Models
  • Event Replay and Rebuilding
  • CQRS Integration

Topic 14: Persistence Strategies

What will be covered:

  • Entity Framework Core Mappings
  • Event Store Implementation
  • Optimistic Concurrency
  • Repository Pattern
  • Unit of Work Pattern
  • Database Migrations
  • Performance Optimization

CYCLE 8: Integration & Bounded Contexts (~2,500 lines)

Topic 15: Bounded Context Integration

What will be covered:

  • Context Map Implementation
  • Shared Kernel
  • Anti-Corruption Layers
  • Published Language (Events)
  • Integration Events vs Domain Events
  • Saga Pattern for Distributed Transactions

Topic 16: Contract Testing & Validation

What will be covered:

  • Aggregate Contract Testing
  • Invariant Validation Tests
  • Domain Event Schema Validation
  • Integration Tests
  • Property-Based Testing
  • Test Data Builders

Summary & Implementation Plan

Implementation Phases

Phase 1: Core Domain (Cycles 1-2) - 2 months - DDD fundamentals and ATP overview - AuditEvent and EventStream aggregates

Phase 2: Tenancy & Policies (Cycles 3-4) - 2 months - Tenant and Policy aggregates - Classification and Retention entities

Phase 3: Services & Rules (Cycles 5-6) - 1.5 months - Value objects and domain services - Invariants and business rules

Phase 4: Persistence & Integration (Cycles 7-8) - 1.5 months - Event sourcing patterns - Bounded context integration

Success Metrics

  • Code Coverage: ≥90% for aggregate logic
  • Invariant Tests: 100% of invariants have executable tests
  • Domain Events: All events documented with schemas
  • Performance: Aggregate operations < 10ms
  • Consistency: Zero invariant violations in production

Ownership & Maintenance

  • Domain Experts: Cycles 1, 3, 6
  • Backend Developers: Cycles 2, 4, 7
  • Architects: Cycles 1, 5, 8
  • QA Engineers: All cycles (test specifications)

Document Status: ✅ Plan Approved - Ready for Content Generation

Target Start Date: Q1 2025

Expected Completion: Q2 2025

Owner: Domain Modeling Team

Last Updated: 2024-10-30