Use cases and interactors

The Use Cases ring and what it owns

In Clean Architecture’s ring model, the Use Cases ring sits directly outside the Entities ring. It contains application-specific business rules — rules that express what this particular application does with the entities.

The distinction matters. An entity contains enterprise-wide business rules: an Order must have at least one line item; an Invoice total must equal the sum of its line items. These rules would be true in any application built on this business. A use case contains application-specific rules: to generate an invoice, first check that the order is confirmed, then check for billing holds, then create the invoice entity, then publish an event. These steps are specific to this application’s process. Different applications built on the same domain (say, a mobile app vs an operations console) might have different use cases but share the same entities.

The Use Cases ring owns:

• One class per use case (the interactor)
• The input port interface (what the use case accepts)
• The output port interface (what the use case produces)
• The request model (the data structure crossing in)
• The response model (the data structure crossing out)

The interactor pattern

An interactor is the class that implements a single use case. It contains the application-logic steps for that use case and nothing else. It does not know about HTTP, SQL, JSON, or any framework concept.

// All types here are in the Use Cases ring — no framework imports
interface GenerateInvoiceInputPort {
  execute(request: GenerateInvoiceRequest): Promise<void>;
}

interface GenerateInvoiceOutputPort {
  presentSuccess(response: GenerateInvoiceResponse): void;
  presentError(error: InvoiceGenerationError): void;
}

class GenerateInvoiceInteractor implements GenerateInvoiceInputPort {
  constructor(
    private readonly orders: IOrderRepository,
    private readonly invoices: IInvoiceRepository,
    private readonly billingHolds: IBillingHoldChecker,
    private readonly presenter: GenerateInvoiceOutputPort,
  ) {}

  async execute(request: GenerateInvoiceRequest): Promise<void> {
    const order = await this.orders.findById(request.orderId);
    if (!order) {
      this.presenter.presentError(new InvoiceGenerationError('ORDER_NOT_FOUND'));
      return;
    }
    if (order.status !== OrderStatus.Confirmed) {
      this.presenter.presentError(new InvoiceGenerationError('ORDER_NOT_CONFIRMED'));
      return;
    }
    const hold = await this.billingHolds.checkForHold(order.customerId);
    if (hold.active) {
      this.presenter.presentError(new InvoiceGenerationError('BILLING_HOLD_ACTIVE'));
      return;
    }
    const invoice = Invoice.createFor(order);
    await this.invoices.save(invoice);
    this.presenter.presentSuccess(new GenerateInvoiceResponse(invoice.id, invoice.total));
  }
}

GenerateInvoiceInteractor is the one canonical place that says: “here is what generating an invoice means.” Every caller — HTTP controller, batch job, CLI, webhook handler — calls this interactor. No caller can skip the billing hold check because it is inside the interactor, not in the caller.

Request models and response models — why they exist

A common early shortcut is to pass the HTTP request object directly into the use case:

// Wrong: Use Cases ring importing a framework type
async execute(req: ExpressRequest): Promise<ExpressResponse>

This creates a source-code dependency from the Use Cases ring to the HTTP framework — an outward-pointing dependency that violates the concentric rule. Worse, it makes the use case untestable without a real HTTP request object.

The fix is request models and response models: plain data structures defined in the Use Cases ring, carrying exactly the data the use case needs in domain terms.

// Correct: Use Cases ring defines its own data shapes
class GenerateInvoiceRequest {
  constructor(
    public readonly orderId: OrderId,
    public readonly requestedBy: UserId,
  ) {}
}

class GenerateInvoiceResponse {
  constructor(
    public readonly invoiceId: InvoiceId,
    public readonly total: Money,
    public readonly generatedAt: Date,
  ) {}
}

The HTTP controller (in Interface Adapters) parses the HTTP request and constructs a GenerateInvoiceRequest. The interactor never sees an ExpressRequest. The interactor produces a GenerateInvoiceResponse. The HTTP presenter (also in Interface Adapters) converts it to a JSON HTTP response. The translation between framework types and use-case types is the Interface Adapters ring’s entire job.

Input ports and output ports

The interactor communicates through two port interfaces, both defined in the Use Cases ring:

Input port (GenerateInvoiceInputPort): the interface the interactor implements. Callers (HTTP controllers, CLI adapters, batch jobs) import this interface and call execute. They never import the concrete interactor class. This means the entire interactor implementation can be swapped or mocked in tests without changing any caller.

Output port (GenerateInvoiceOutputPort): the interface the interactor calls to deliver results. The interactor does not return a value — it calls the output port, which the Interface Adapters ring implements (as a presenter). This is the dependency inversion applied to the response side: the interactor does not know about HTTP status codes, JSON serialization, or streaming — it calls a domain-language method like presentSuccess(response) and lets the presenter decide how to render it.

This two-port structure mirrors hexagonal architecture’s primary and secondary ports, now applied specifically at the Use Cases ring boundary. The interactor is the application “hexagon” for that one use case.