adaptive_pipeline/application.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//! # Application Layer
9//!
10//! The application layer orchestrates business workflows and coordinates
11//! between the domain layer and external systems. It implements the use cases
12//! of the system and serves as the entry point for all business operations.
13//!
14//! ## Architecture
15//!
16//! The application layer follows the Clean Architecture pattern and acts as a
17//! coordination layer that:
18//!
19//! - Receives requests from the interface layer
20//! - Coordinates domain services and entities
21//! - Manages transactions and cross-cutting concerns
22//! - Transforms data between layers
23//! - Handles application-specific business rules
24//!
25//! ## Module Structure
26//!
27//! ```text
28//! application/
29//! ├── commands/ # Command objects representing user intentions
30//! ├── handlers/ # Command and query handlers
31//! ├── queries/ # Query objects for data retrieval
32//! └── services/ # Application services coordinating workflows
33//! ```
34//!
35//! ## Commands
36//!
37//! Commands represent user intentions and system operations. They are immutable
38//! data structures that encapsulate all the information needed to perform an
39//! action.
40//!
41//! **Characteristics:**
42//! - Immutable data structures
43//! - Self-validating
44//! - Express user intent
45//! - Contain all necessary parameters
46//!
47//! **Example:**
48//!
49//!
50//! ## Queries
51//!
52//! Queries represent requests for data retrieval. They specify what data is
53//! needed and any filtering or sorting criteria.
54//!
55//! **Characteristics:**
56//! - Read-only operations
57//! - Specify data requirements
58//! - Support filtering and pagination
59//! - Return DTOs or view models
60//!
61//! **Example:**
62//!
63//!
64//! ## Handlers
65//!
66//! Handlers contain the application logic for processing commands and queries.
67//! They coordinate between domain services and manage the flow of operations.
68//!
69//! **Characteristics:**
70//! - Stateless operations
71//! - Coordinate domain services
72//! - Manage transactions
73//! - Handle cross-cutting concerns
74//!
75//! **Example:**
76//!
77//!
78//! ## Application Services
79//!
80//! Application services implement complex workflows that span multiple domain
81//! services or require coordination with external systems.
82//!
83//! **Characteristics:**
84//! - Orchestrate complex workflows
85//! - Manage external dependencies
86//! - Handle application-specific logic
87//! - Provide transaction boundaries
88//!
89//! **Example:**
90//!
91//!
92//! ## Design Principles
93//!
94//! ### Dependency Inversion
95//! The application layer depends on domain abstractions, not concrete
96//! implementations. All external dependencies are injected through interfaces.
97//!
98//! ### Single Responsibility
99//! Each application service, handler, and command has a single, well-defined
100//! purpose.
101//!
102//! ### Separation of Concerns
103//! Commands handle data, handlers handle logic, services handle coordination.
104//!
105//! ### Testability
106//! All components are designed to be easily testable with dependency injection
107//! and clear interfaces.
108//!
109//! ## Error Handling
110//!
111//! The application layer handles errors from the domain layer and translates
112//! them into appropriate responses for the interface layer:
113//!
114//!
115//! ## Testing Strategy
116//!
117//! Application layer components are tested with:
118//!
119//! - **Unit Tests**: Test individual handlers and services with mocked
120//! dependencies
121//! - **Integration Tests**: Test complete workflows with real implementations
122//! - **Contract Tests**: Verify interfaces between layers
123
124pub mod commands;
125pub mod services;
126pub mod use_cases;
127pub mod utilities;