Where layering leaks

Leak 1: The transaction-script trap

The transaction-script trap is what happens when layering is applied structurally but the team’s mental model stays procedural. Each use case becomes a long procedure in a service method — step 1, step 2, step 3, if this then that — with the domain objects as passive data containers that the procedure manipulates.

// Transaction script masquerading as a layered architecture
class OrderService {
  async confirmOrder(orderId: string, userId: string): Promise<void> {
    // Step 1: load
    const order = await this.orderRepo.findById(orderId);
    const user = await this.userRepo.findById(userId);
    const invoices = await this.invoiceRepo.findByOrderId(orderId);

    // Step 2: validate (all logic inline, none in the domain)
    if (order.status !== 'pending') throw new Error('Not pending');
    if (!user.hasRole('manager')) throw new Error('Unauthorized');
    if (invoices.some(i => i.status === 'overdue')) throw new Error('Overdue invoices');
    if (order.totalAmount > 10000 && !order.approvalId) throw new Error('Needs approval');

    // Step 3: mutate (directly setting fields)
    order.status = 'confirmed';
    order.confirmedAt = new Date();
    order.confirmedBy = userId;

    // Step 4: side effects (service directly calls infrastructure)
    await this.orderRepo.save(order);
    await this.emailClient.send(order.customerEmail, 'Order confirmed', ...);
    await this.eventBus.publish({ type: 'OrderConfirmed', orderId });
  }
}

The layers exist but the logic lives in one long procedure inside the service. Testing this method requires a real database (or mocking 5 dependencies). Adding a new rule means editing the procedure. The domain layer has no behavior — the service is both the application layer and the domain layer simultaneously.

This is the Transaction Script pattern masquerading as layered architecture. The service package and the domain package are both technically present — but the domain package is empty of real logic, and the service package has absorbed everything.

Leak 2: Layer-skipping and leaky abstractions

Layer-skipping occurs when a higher layer imports from a lower layer, bypassing the intermediate layers. The canonical violation: a controller that imports a repository class directly.

// Controller importing infrastructure directly
import { PostgresOrderRepository } from '../infra/PostgresOrderRepository';

class BillingReportController {
  private repo = new PostgresOrderRepository();

  async getBillingReport(req: Request): Promise<Response> {
    // Direct SQL in the controller
    const rows = await this.repo.findRawSql(`
      SELECT o.id, o.total_amount, i.invoice_number
      FROM orders o JOIN invoices i ON i.order_id = o.id
      WHERE o.status = 'confirmed' AND o.confirmed_at > $1
    `, [req.query.since]);
    return Response.json(rows);
  }
}

This is the getBillingReportData problem from the opening story. The developer needed a specific SQL join that no existing service or domain method exposed. Rather than add a method to the appropriate layer, they reached directly into infrastructure.

The leak is self-reinforcing. Once one controller imports a repository, other developers see the pattern and repeat it. Within months, controllers throughout the application have direct repository dependencies. The infrastructure layer is now directly coupled to the presentation layer — swapping the database requires changing controllers.

Leaky abstractions are a subtler form of the same failure: the abstraction boundary nominally exists, but implementation details from a lower layer bleed through it. A domain service that returns a Knex.QueryBuilder object instead of a domain type leaks the query builder into the layer above. A repository interface that exposes an EntityManager parameter leaks the ORM into the application layer. The caller now depends on implementation details even though there is an apparent interface boundary.

Leak 3: The fat service and the god object

The fat service is the end state of an application where all business logic gravitates to the service layer. It starts with reasonable methods — createOrder, confirmOrder, cancelOrder — and grows as features accumulate. After 18 months, OrderService has 61 methods and imports from 11 different dependencies.

The fat service has the structural properties of a god object:

• It knows about everything: infrastructure clients, domain entities, external services, reporting queries, notification logic, audit logging.
• Everything depends on it: presentation layer, background jobs, batch processors, integration adapters.
• It is untestable in isolation: instantiating OrderService requires mocking 11 dependencies. A test for confirmOrder must configure the full dependency tree.
• Changes ripple everywhere: modifying OrderService can affect any of its 61 callers.

The fat service is the result of a correct layering instinct — keep business logic out of controllers — combined with the absence of a domain layer that can absorb that logic. Without a rich domain model to hold invariants and entities, and without clear use-case boundaries in the application layer, the service layer becomes the catch-all.

// What a fat OrderService imports after 18 months:
import { OrderRepository } from '../infra/OrderRepository';
import { InvoiceRepository } from '../infra/InvoiceRepository';
import { UserRepository } from '../infra/UserRepository';
import { StripeClient } from '../infra/StripeClient';
import { SendGridClient } from '../infra/SendGridClient';
import { PDFGenerator } from '../infra/PDFGenerator';
import { S3Client } from '../infra/S3Client';
import { EventBus } from '../infra/EventBus';
import { AuditLogger } from '../infra/AuditLogger';
import { ReportingQueryRunner } from '../infra/ReportingQueryRunner';
import { FeatureFlagClient } from '../infra/FeatureFlagClient';

The service layer has become the integration layer. It is not orchestrating domain logic — it IS the domain logic, mixed with infrastructure calls. Extracting a single use case (say, order confirmation) requires untangling it from 61 other methods sharing the same dependency tree.

Why these leaks motivated hexagonal and clean architecture

Each of the three leaks points to a structural gap in flat n-tier layering:

The transaction-script trap points to the gap: no mechanism forces the domain layer to contain real logic. A flat four-layer stack does not prevent a service from absorbing all behavior.

Layer-skipping points to the gap: no mechanism prevents higher layers from importing lower layers. The dependency rule is a convention, not a structural constraint. Nothing in a plain package structure stops a controller from importing a repository.

The fat service points to the gap: no mechanism defines the boundary of a use case. A service class can grow without limit, absorbing concerns that should be in separate components.

Hexagonal architecture (unit 04) addresses all three by inverting the dependency at the domain boundary. The domain owns its ports — the interfaces it needs from the outside world. No infrastructure class can be imported by the domain because the domain defines the interface and infrastructure implements it. The service (application layer) is bounded by its primary port, not by a class that happens to live in a “services” package. The inside of the hexagon (domain + application) is testable without any infrastructure at all, because the infrastructure is always behind an interface the domain owns.

Clean architecture (unit 05) generalizes this to concentric layers with the same dependency rule: no inner layer imports any outer layer. The entity core, the use-case ring, the interface adapters, and the frameworks/drivers are separated by hard dependency constraints — not by package naming conventions.