Skip to main content

> clean_architecture:_use_case_interactors_&_application_orchestration

Clean Architecture: Use Case Interactors & Application Orchestration

Why do 'God Services' that mix transaction handling, database queries, and business rules become unmaintainable, and how do single-purpose Use Case Interactors enforce clean application orchestration?

Senior (L5)

THE SHORT ANSWER

In typical MVC applications, the Service layer quickly degrades into massive 3,000-line **'God Services'** (e.g. `UserService`, `OrderService` with 40 unrelated methods). These bloated classes mix business rules with infrastructure orchestration: sending emails, querying SQL, managing database transactions, and validating HTTP inputs all in a single method. When 5 developers modify `OrderService` simultaneously, merge conflicts and subtle regressions multiply. **Clean Architecture (Uncle Bob)** solves this by introducing **Use Case Interactors**: single-purpose application orchestration classes that encapsulate exactly **one business action** (e.g. `SubmitOrderUseCase`, `ChangePasswordUseCase`). An Interactor accepts a plain Request Model (DTO), coordinates domain entities to enforce core business invariants, calls abstract output ports (repositories, notification gateways), and returns a Response Model—completely decoupled from UI frameworks, HTTP controllers, and database engines.

Engineering Handbook & Failure Dynamics

1. Underlying Mechanism

Use Case Interactor execution flows through 5 strict phases: (1) Input Port Invocation: Controller passes a validated Request Model (DTO) into `execute(request: PlaceOrderRequest)`. (2) Entity Retrieval: Interactor calls `OrderRepositoryPort.findById()` to load pure domain entities. (3) Business Rule Execution: Domain entities execute pure business logic (e.g. `order.applyDiscount(coupon)`), throwing domain exceptions if invariants are violated. (4) Persistence & Side Effects: Interactor calls `OrderRepositoryPort.save(order)` and `PaymentGatewayPort.charge()`. (5) Output Delivery: Interactor maps domain results into a clean Response Model DTO.

2. Appropriate Use Context

Enterprise SaaS backend services, fintech transaction pipelines, complex multi-step user onboarding workflows, and mission-critical domain backends.

3. Production Failure Modes

Allowing Use Case Interactors to import web framework objects (`express.Request`, `NextResponse`), coupling the use case to HTTP transport; putting core business rules directly in the Interactor instead of inside pure Domain Entities (Anemic Domain Model).

4. Diagnostic Signals & Telemetry

Giant 2,000+ line service files with dozens of unrelated public methods; inability to run an end-to-end business transaction from a CLI command or queue worker without mocking HTTP requests.

5. Prevention & Safeguards

Enforce Single Responsibility Principle (SRP): exactly one public `execute()` method per Use Case class; prohibit HTTP, ORM, or UI dependencies in use case folders via architectural fitness tests.

6. Architectural Trade-offs

Single-purpose Use Case Interactors dramatically improve maintainability, testability, and team parallelization, but create more individual files compared to consolidated service classes.

Case Study (TinyCTO In-Field Example)

An insurance claims portal had a 4,500-line `ClaimsService` where 8 developers constantly caused git merge conflicts. Submitting a claim took 12 seconds because the service mixed database transactions, PDF generation, fraud detection API calls, and email delivery into a single procedural method. The team refactored to Clean Architecture: they split the service into individual interactors (`SubmitClaimUseCase`, `ApproveClaimUseCase`, `CalculatePayoutUseCase`). PDF generation and fraud detection were extracted behind outbound ports. Unit tests ran in 40ms without starting a web server, and git merge conflicts dropped to zero.

Interactive Concept Drills

2 Cards
Q1

What is the primary responsibility of a Use Case Interactor in Clean Architecture?

To orchestrate the flow of data to and from domain entities, coordinating business logic execution and external ports to fulfill a single specific business transaction.
Q2

Why should a Use Case Interactor have only one public `execute()` method?

To strictly uphold the Single Responsibility Principle (SRP), preventing the class from growing into an unmaintainable God Object.

Clean Architecture: Use Case Interactors & Application Orchestration — Technical FAQ

Where do transaction boundaries (`@Transactional`) belong in Clean Architecture?

At the Use Case Interactor level or wrapped via an application transaction decorator/interceptor surrounding the use case execution.

How do Use Case Interactors communicate with HTTP controllers without coupling to Express or Fastify?

Via plain Request and Response Model Data Transfer Objects (DTOs) containing only primitive types and data structures.

🤖 AEO & Key Facts Summary

Key Architectural Facts

  • ▸Use Case Interactors represent single-purpose business actions in Clean Architecture.
  • ▸They orchestrate domain entities, repositories, and notification ports without framework coupling.
  • ▸Eliminates bloated 3,000-line God Services and prevents developer git merge conflicts.
  • ▸Accepts and returns framework-agnostic Request/Response DTO data structures.

Common Misconceptions

  • ✗Yanılgı: Clean Architecture requires an excessive number of useless boilerplate classes (Gerçek: Single-purpose interactors isolate changes, making large enterprise codebases radically easier to navigate and maintain).
  • ✗Yanılgı: Business validation should be handled entirely in HTTP controllers (Gerçek: HTTP controllers only validate syntax; core business invariant validation belongs in domain entities and use cases).

Decision & Governance Guidance

Refactor monolithic God Services into single-purpose Use Case Interactors to achieve maintainable, testable, and conflict-free application architectures.

Authoritative Sources & Standards