Clean Architecture: Use Case Interactors & 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

6-Dimensional Architecture Breakdown

⚙️1. Underlying Mechanism

Execution

Use Case Interactor execution flows through 5 strict phases:

Input Port Invocation: Controller passes a validated Request Model (DTO) into execute(request: PlaceOrderRequest).

Entity Retrieval: Interactor calls OrderRepositoryPort.findById() to load pure domain entities.

Business Rule Execution: Domain entities execute pure business logic (e.g. order.applyDiscount(coupon)), throwing domain exceptions if invariants are violated.

Persistence & Side Effects: Interactor calls OrderRepositoryPort.save(order) and PaymentGatewayPort.charge().

Output Delivery: Interactor maps domain results into a clean Response Model DTO.

🎯2. Appropriate Use Context

Scope

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

⚠️3. Production Failure Modes

P0 Risk

✓
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

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

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

Trade-off

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)

REAL-WORLD TELEMETRY

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

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.

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

[BOOK]Clean Architecture: A Craftsman's Guide to Software Structure and Design (Use Cases & Interactors)— Robert C. Martin (Uncle Bob / Prentice Hall)

Technical terms on this page

Merge