Skip to main content

Use Cases and Business Logic

Reading time: ~15 minutes

Introduction​

A critical aspect of Prism Architecture is how it organizes and structures business logic, particularly through its Orchestration Layer. This document explores the hierarchical approach to use cases and business logic in Prism Architecture, explaining how the architecture maintains separation of concerns while providing a clear structure for organizing application functionality.

Unlike simpler architectures that might place business logic in various places throughout the application, Prism Architecture creates a structured approach with clear boundaries and responsibilities. This organization not only improves maintainability but also enhances testability and makes the system more adaptable to changing requirements.

Business Logic Placement​

Domain vs. Orchestration Logic​

Prism Architecture makes a clear distinction between two types of business logic:

  1. Domain Logic: Pure business rules, validations, and calculations that represent the core knowledge of the business domain
  2. Orchestration Logic: The coordination and sequencing of operations across different parts of the system

These two types of logic are deliberately separated in Prism Architecture:

  • Domain Logic resides in the Domain Layer, typically within Domain Services and Entities
  • Orchestration Logic resides in the Orchestration Layer, within Use Cases, Orchestration Services, and Workflows

This separation allows domain experts to focus on capturing business rules correctly while application developers can focus on implementing the flow of operations without mixing concerns.

The Hierarchical Orchestration Structure​

One of the key innovations in Prism Architecture is its hierarchical approach to orchestration components. Rather than treating all use cases equally, Prism defines a clear hierarchy with progressively expanding capabilities and scope.

This hierarchy consists of three levels of components, each with specific responsibilities and boundaries:

  1. Use Cases: Entity-focused, atomic operations
  2. Orchestration Services: Feature/aggregate-level coordination
  3. Workflows: Cross-domain processes

Let's explore each level in detail.

Use Cases​

Definition and Characteristics​

Use Cases in Prism Architecture implement specific, well-defined operations that focus on a single entity within an aggregate. They represent atomic business operations with a clear, narrow focus.

Key characteristics of Use Cases include:

  • Single Entity Focus: Each Use Case works with a single entity within an aggregate
  • Atomic Operations: They handle specific, indivisible operations
  • Clear Naming: Named with verb-noun combinations (e.g., RegisterUserUseCase)
  • Coordination Role: They coordinate between Domain, Infrastructure, and Presentation layers
  • Minimal Logic: They contain minimal logic beyond coordination

Boundaries and Constraints​

Use Cases operate within strict boundaries:

  • Limited to operations on a single entity within an aggregate
  • Cannot call other Use Cases
  • Can use Domain Services for business logic
  • Can use Infrastructure Services for external operations

These constraints ensure that Use Cases remain focused and maintainable, handling only one specific operation at a time.

Common Use Case Patterns​

Typical patterns for Use Cases include:

  1. CRUD Operations: Create, Read, Update, Delete operations for entities
  2. State Transitions: Moving entities through defined state changes
  3. Validation and Processing: Validating input and performing specific operations
  4. Simple Queries: Retrieving data for specific use cases

Example Use Cases​

Examples of well-defined Use Cases include:

  • RegisterUserUseCase: Handles user registration
  • UpdateProductDetailsUseCase: Updates a product's information
  • PlaceOrderUseCase: Processes an order placement
  • CancelSubscriptionUseCase: Handles subscription cancellation

Orchestration Services​

Definition and Characteristics​

Orchestration Services manage related operations within a particular feature area or aggregate. They can compose multiple Use Cases but only within the same feature boundary.

Key characteristics of Orchestration Services include:

  • Feature Area Focus: Each service manages a cohesive feature area
  • Composition Capability: Can compose multiple Use Cases within a feature
  • Naming Convention: Named after feature domains (e.g., AuthenticationOrcService)
  • State Management: May maintain feature-specific state or context
  • Feature API: Provide a cohesive API for related operations

Boundaries and Constraints​

Orchestration Services operate within defined boundaries:

  • Limited to operations within a single feature domain or aggregate
  • Can compose and call multiple Use Cases
  • Cannot call or depend on Orchestration Services from different domains
  • Serve as the middle tier in the component hierarchy

These constraints ensure that Orchestration Services maintain clear feature-based cohesion while being able to coordinate more complex operations than individual Use Cases.

Common Orchestration Patterns​

Typical patterns for Orchestration Services include:

  1. Feature Composition: Combining multiple Use Cases into feature workflows
  2. State Management: Maintaining context across multiple related operations
  3. Transaction Management: Ensuring consistency across multiple operations
  4. Feature-Level Validation: Validating complex constraints across related entities

Example Orchestration Services​

Examples of well-defined Orchestration Services include:

  • AuthenticationOrcService: Manages authentication-related operations
  • OrderManagementOrcService: Coordinates various order-related operations
  • SubscriptionOrcService: Handles subscription-related functionality
  • ProfileManagementOrcService: Manages user profile-related operations

Workflow Coordinators​

Definition and Characteristics​

Workflow Coordinators manage complex, multi-step processes that may involve multiple feature areas and aggregates. They can compose both Use Cases and Services from different domains.

Key characteristics of Workflow Coordinators include:

  • Cross-Domain Scope: Work across different aggregates and domains
  • Process Focus: Handle end-to-end business processes
  • Naming Convention: Named after processes (e.g., CheckoutWorkflow)
  • State Management: Manage state transitions throughout a process
  • Complex Coordination: Coordinate across multiple feature areas

Boundaries and Constraints​

Workflow Coordinators have the broadest scope in the hierarchy:

  • Can work across multiple feature domains and aggregates
  • Can compose both Use Cases and Orchestration Services
  • Represent the highest level in the component hierarchy
  • Used only for genuinely complex processes that span multiple domains

Despite their broader scope, Workflows should still be focused on specific business processes rather than becoming catch-all components.

Common Workflow Patterns​

Typical patterns for Workflow Coordinators include:

  1. Multi-Stage Processes: Managing processes with distinct stages
  2. Cross-Domain Coordination: Coordinating actions across domain boundaries
  3. Saga Pattern: Managing compensating transactions for complex operations
  4. State Machine Implementation: Implementing complex state transitions

Example Workflow Coordinators​

Examples of well-defined Workflow Coordinators include:

  • CheckoutWorkflow: Manages the complete checkout process
  • OnboardingWorkflow: Coordinates user onboarding across multiple features
  • PaymentProcessingWorkflow: Handles the end-to-end payment process
  • ContentPublishingWorkflow: Manages the content creation and publishing process

Business Logic Implementation Patterns​

Domain-Driven Logic​

Prism Architecture emphasizes implementing core business rules in the Domain Layer:

  1. Domain Services: For business logic that doesn't belong to a single entity
  2. Entity Methods: For entity-specific business rules
  3. Validation Services: For complex validation rules
  4. Domain Events: For reactive business processes

This approach keeps the core business rules centralized and consistent.

Use Case Structure Pattern​

A typical Use Case in Prism Architecture follows this pattern:

  1. Input Validation: Validating input parameters
  2. Permission Checking: Verifying the operation is allowed
  3. Domain Logic Delegation: Calling appropriate Domain Services
  4. Infrastructure Coordination: Using repositories or other services
  5. Result Composition: Creating the appropriate response

This consistent structure makes Use Cases predictable and maintainable.

Orchestration Service Composition​

Orchestration Services typically compose Use Cases in one of several patterns:

  1. Sequential Composition: Executing Use Cases in sequence
  2. Conditional Branching: Selecting Use Cases based on conditions
  3. Parallel Execution: Running independent Use Cases concurrently
  4. Aggregation: Combining results from multiple Use Cases

These composition patterns allow for flexible coordination of functionality.

Communication Patterns​

Command-Based Communication​

Prism Architecture typically uses command objects for communication with the Orchestration Layer:

  1. Command Objects: Immutable objects representing operation requests
  2. Result Objects: Structured responses containing operation results
  3. Validation Results: Specialized results for validation outcomes
  4. Error Handling: Standardized approach to error communication

This pattern creates explicit, traceable communication between layers.

Event-Based Communication​

For asynchronous processes, Prism Architecture uses an event-based approach:

  1. Domain Events: Generated by Domain Layer to indicate significant occurrences
  2. Event Handlers: In the Orchestration Layer to respond to events
  3. Workflow Triggers: Events that initiate or advance workflows
  4. Presentation Notifications: Events sent to the Presentation Layer

This approach enables reactive behavior while maintaining layer separation.

Testing Business Logic​

Domain Logic Testing​

Testing Domain Layer components focuses on business rules:

  1. Domain Service Tests: Verify business rule implementation
  2. Entity Tests: Ensure entity constraints and behavior
  3. Validation Logic Tests: Confirm validation rule correctness
  4. Domain Event Tests: Verify event generation under appropriate conditions

These tests focus on business correctness, not technical integration.

Orchestration Component Testing​

Testing Orchestration Layer components focuses on coordination:

  1. Use Case Tests: Verify correct orchestration of dependencies
  2. Orchestration Service Tests: Confirm proper composition of Use Cases
  3. Workflow Tests: Ensure correct process flow and state management
  4. Event Handler Tests: Verify appropriate reactions to events

These tests use mocks for dependencies to isolate orchestration logic.

Practical Implementation Guidance​

Balancing Business Logic Placement​

When deciding where to place business logic, follow these guidelines:

  1. Domain Layer for:

    • Core business rules and invariants
    • Entity validation and constraints
    • Business calculations and algorithms
    • Domain-specific operations

  2. Orchestration Layer for:

    • Operation sequencing and coordination
    • Transaction management
    • Cross-entity orchestration
    • Integration with external systems

Maintaining the Hierarchy​

To maintain a clean hierarchical structure:

  1. Start Simple: Begin with Use Cases for individual operations
  2. Group by Feature: Create Orchestration Services for related functionality
  3. Identify Workflows: Extract cross-domain processes into Workflows
  4. Refactor Continuously: Adjust the hierarchy as the application evolves

Component Organization​

The Orchestration Layer typically follows this folder structure:

This structure reflects the hierarchical organization of components.

Common Anti-Patterns to Avoid​

Use Case Anti-Patterns​

  1. Bloated Use Cases: Including too much functionality in a single Use Case
  2. Domain Logic in Use Cases: Placing business rules that belong in the Domain Layer
  3. Direct Infrastructure Access: Bypassing abstractions to access infrastructure
  4. Use Case Chaining: Having Use Cases call other Use Cases

Orchestration Service Anti-Patterns​

  1. Aggregate-Based Services: Creating services based solely on Aggregates (e.g., UserOrcService) rather than features
  2. Operation-Splitting Services: Creating separate services for CRUD operations on the same entity
  3. Cross-Domain Services: Services that span multiple unrelated domains
  4. Stateless-Only Thinking: Failing to maintain necessary context between operations

Workflow Anti-Patterns​

  1. Monolithic Workflows: Trying to handle too many processes in one Workflow
  2. Missing State Management: Not properly tracking process state
  3. Hardcoded Flow: Building workflows that can't adapt to variations
  4. Technical Process Focus: Creating workflows around technical rather than business processes

Real-World Examples​

E-Commerce Order Processing​

In an e-commerce application, the order processing might be structured as:

Use Cases:

  • ValidateOrderUseCase: Validates order details
  • CalculateOrderTotalsUseCase: Calculates order totals
  • ReserveInventoryUseCase: Reserves inventory for items

Orchestration Service:

  • OrderManagementOrcService: Coordinates order-related operations

Workflow:

  • CheckoutWorkflow: Manages the end-to-end checkout process across payment, inventory, and order domains

User Management​

In a SaaS application, user management might be structured as:

Use Cases:

  • RegisterUserUseCase: Handles user registration
  • UpdateUserProfileUseCase: Updates user profile details
  • ChangeUserPasswordUseCase: Changes user password

Orchestration Service:

  • UserManagementOrcService: Coordinates user-related operations

Workflow:

  • OnboardingWorkflow: Manages the complete user onboarding process across authentication, profile setup, and permissions domains

Conclusion​

The hierarchical approach to use cases and business logic in Prism Architecture creates a structured, maintainable way to organize application functionality. By clearly separating domain logic from orchestration logic and using a tiered hierarchy of orchestration components, Prism Architecture provides both clarity and flexibility.

The three-level hierarchy of Use Cases, Orchestration Services, and Workflows creates natural boundaries that align with the complexity of operations. Simple, entity-focused operations are handled by Use Cases, feature-area coordination by Orchestration Services, and complex cross-domain processes by Workflows.

By following these patterns and avoiding anti-patterns, developers can create applications that are both well-structured and adaptable to changing requirements.

Next Steps​

  • Domain Services: Explore how Domain Services implement core business logic
  • Infrastructure Integration: Understand how the Orchestration Layer interfaces with the Infrastructure Layer
  • Presentation Layer Integration: Learn how the Orchestration Layer communicates with the Presentation Layer
  • Event-Driven Architecture: Discover how events enable reactive behavior in Prism Architecture