adaptive_pipeline_domain/aggregates.rs
1// /////////////////////////////////////////////////////////////////////////////
2// Adaptive Pipeline
3// Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
4// SPDX-License-Identifier: BSD-3-Clause
5// See LICENSE file in the project root.
6// /////////////////////////////////////////////////////////////////////////////
7
8//! # Domain Aggregates
9//!
10//! This module contains the domain aggregates - complex domain objects that
11//! serve as consistency boundaries and transaction roots in the Domain-Driven
12//! Design (DDD) architecture. Aggregates encapsulate business logic, maintain
13//! invariants, and coordinate changes across multiple related entities.
14//!
15//! ## Overview
16//!
17//! Aggregates in this pipeline processing system provide:
18//!
19//! - **Consistency Boundaries**: Ensure all business rules are enforced within
20//! the aggregate
21//! - **Transaction Roots**: Serve as the entry point for all operations within
22//! the boundary
23//! - **Event Sourcing**: Generate and apply domain events for state changes
24//! - **Concurrency Control**: Manage optimistic locking through version
25//! tracking
26//! - **Business Logic Encapsulation**: Contain complex domain operations and
27//! validations
28//!
29//! ## Domain-Driven Design Principles
30//!
31//! ### Aggregate Root Pattern
32//!
33//! Each aggregate has a single root entity that:
34//!
35//! - **Controls Access**: All external access goes through the aggregate root
36//! - **Maintains Identity**: Provides unique identification for the entire
37//! aggregate
38//! - **Enforces Invariants**: Validates business rules before allowing state
39//! changes
40//! - **Publishes Events**: Generates domain events for significant state
41//! changes
42//! - **Manages Lifecycle**: Controls creation, modification, and deletion of
43//! contained entities
44//!
45//! ### Consistency Boundaries
46//!
47//! Aggregates define consistency boundaries by:
48//!
49//! - **Immediate Consistency**: All changes within an aggregate are immediately
50//! consistent
51//! - **Eventual Consistency**: Changes across aggregates achieve consistency
52//! eventually
53//! - **Transaction Scope**: Each aggregate represents a single transaction
54//! boundary
55//! - **Invariant Protection**: Business rules are enforced at the aggregate
56//! level
57//!
58//! ### Event Sourcing Integration
59//!
60//! Aggregates support event sourcing patterns through:
61//!
62//! - **Event Generation**: Create domain events for all state changes
63//! - **Event Application**: Apply historical events to reconstruct state
64//! - **State Reconstruction**: Rebuild aggregate state from event streams
65//! - **Optimistic Concurrency**: Use version numbers to detect concurrent
66//! modifications
67//!
68//! ## Available Aggregates
69//!
70//! ### PipelineAggregate
71//!
72//! The `PipelineAggregate` is the primary aggregate root that manages:
73//!
74//! - **Pipeline Configuration**: Core pipeline settings and stage definitions
75//! - **Processing Coordination**: Active file processing operations and their
76//! contexts
77//! - **Event Management**: Domain events for pipeline lifecycle and processing
78//! operations
79//! - **State Validation**: Business rule enforcement for all pipeline
80//! operations
81//!
82//! ## Usage Patterns
83//!
84//! ### Creating New Aggregates
85//!
86//!
87//!
88//! ### Event Sourcing Reconstruction
89//!
90//!
91//!
92//! ### Repository Integration
93//!
94//!
95//!
96//! ## Best Practices
97//!
98//! ### Aggregate Design
99//!
100//! - **Keep Aggregates Small**: Include only entities that must be consistent
101//! together
102//! - **Single Responsibility**: Each aggregate should have a focused business
103//! purpose
104//! - **Avoid Deep Hierarchies**: Limit the depth of entity relationships within
105//! aggregates
106//! - **Event-Driven Communication**: Use domain events for inter-aggregate
107//! communication
108//!
109//! ### Transaction Management
110//!
111//! - **One Aggregate Per Transaction**: Modify only one aggregate per
112//! transaction
113//! - **Eventual Consistency**: Accept eventual consistency between aggregates
114//! - **Optimistic Concurrency**: Use version numbers to detect concurrent
115//! modifications
116//! - **Event Persistence**: Persist events atomically with aggregate state
117//!
118//! ### Performance Considerations
119//!
120//! - **Lazy Loading**: Load aggregate data only when needed
121//! - **Event Snapshots**: Use snapshots to avoid replaying long event streams
122//! - **Caching Strategy**: Cache frequently accessed aggregates appropriately
123//! - **Batch Operations**: Group related operations to minimize transaction
124//! overhead
125//!
126//! ## Error Handling
127//!
128//! Aggregates provide comprehensive error handling:
129//!
130//! - **Validation Errors**: Business rule violations are caught and reported
131//! - **Concurrency Conflicts**: Version conflicts are detected and handled
132//! - **State Consistency**: Invalid state transitions are prevented
133//! - **Event Application**: Event replay failures are handled gracefully
134//!
135//! ## Testing Strategies
136//!
137//! ### Unit Testing
138//!
139//! Test aggregates in isolation:
140//!
141//!
142//! ### Integration Testing
143//!
144//! Test aggregates with repositories and event stores:
145
146pub mod pipeline_aggregate;
147
148pub use pipeline_aggregate::PipelineAggregate;