Domain-Driven Design: Clean Architecture, cómo proteger el modelo de dominio mediante dependencias bien diseñadas.

El controlador que tiene que saberlo todo

La confirmación de pedidos empieza como una ruta pequeña. Después incorpora comprobaciones de pago, reserva de existencias, estados y persistencia. Para probar una regla, el equipo necesita levantar Express y preparar una base de datos.

Cambiar un nombre de columna obliga a revisar lógica comercial. Ejecutar la misma operación desde otra entrada implica copiar parte del controlador.

Este es un contraejemplo didáctico; db representa un cliente SQL no implementado aquí:

app.post("/orders/:id/confirm", async (req, res) => {
  const row = await db.findOrder(req.params.id);

  if (!row) {
    res.status(404).json({ error: "ORDER_NOT_FOUND" });
    return;
  }

  if (
    row.status === "CANCELLED" ||
    row.item_count === 0 ||
    !row.payment_confirmed ||
    !row.stock_reserved
  ) {
    res.status(409).json({ error: "ORDER_CANNOT_BE_CONFIRMED" });
    return;
  }

  await db.updateOrder(req.params.id, { status: "CONFIRMED" });
  res.json({ orderId: req.params.id, status: "CONFIRMED" });
});

Además de los controles omitidos, la ruta mezcla transporte, representación de datos y decisión comercial. Separarlos en archivos no bastará si las dependencias siguen apuntando a los detalles técnicos.

Vamos a refactorizar este ejemplo dentro del contexto Sales. Supondremos que las reglas ya se descubrieron y que el objetivo ahora es protegerlas.

DDD y Clean Architecture resuelven preguntas diferentes

DDD ayuda a representar conocimiento y reglas del negocio. Clean Architecture busca proteger políticas internas frente a detalles como transporte o almacenamiento.

Su Dependency Rule establece que las dependencias del código fuente apuntan hacia las políticas internas. Una capa interna no debe conocer tipos definidos por una externa. No se refiere simplemente al orden de llamadas durante la ejecución. Robert C. Martin: The Clean Architecture.

El modelo clásico distingue:

• Entities: políticas de negocio generales.
• Use Cases: comportamiento específico de la aplicación.
• Interface Adapters: conversión entre representaciones.
• Frameworks & Drivers: herramientas y mecanismos externos.

Podemos relacionarlos con Domain, Application, Presentation e Infrastructure, pero no son equivalencias exactas. Por ejemplo, adaptadores HTTP y de persistencia pertenecen conceptualmente a Interface Adapters, aunque un proyecto los organice en directorios distintos.

«Entities» de Clean Architecture tampoco equivale únicamente al patrón Entity de DDD. Lo importante aquí es qué conocimiento protegemos y quién puede depender de él.

Dibujar imports y llamadas por separado

Para nuestro ejemplo proponemos:

Dependencias de código:

Controlador HTTP ---> Caso de uso ---> Modelo Order
Adaptador memoria --> Puerto OrderRepository ---> Modelo Order
Composición --------> Implementaciones que conecta

Durante una petición, el caso de uso invocará el repositorio concreto. Sin embargo, su código conocerá solo un contrato interno.

Eso es inversión de dependencias: el comportamiento de aplicación no importa la implementación de almacenamiento; el adaptador implementa la capacidad que la aplicación necesita.

No hace falta un contenedor para lograrlo. Un constructor que recibe la dependencia puede ser suficiente.

Alcance y reglas del ejemplo

Para esta tienda ficticia acordamos que un pedido se puede confirmar cuando:

• No está cancelado.
• Contiene al menos una línea.
• Sales dispone de confirmación de pago y reserva correspondientes.
• Una confirmación repetida de un pedido ya confirmado no cambia su estado.

Los indicadores de pago y reserva son hechos locales previamente verificados. No se aceptan desde el cuerpo HTTP ni demuestran por sí solos una integración completa.

No implementaremos cobros o reservas. Si esos hechos proceden de otros contextos, deben obtenerse mediante contratos y traducciones del consumidor, sin importar sus entidades.

Un modelo Order que no importa Express

En sales/domain/order.ts:

export interface OrderSnapshot {
  readonly id: string;
  readonly status: "PENDING" | "CONFIRMED" | "CANCELLED";
  readonly itemCount: number;
  readonly paymentConfirmed: boolean;
  readonly stockReserved: boolean;
}

export class OrderRuleError extends Error {}

export class Order {
  private constructor(private state: OrderSnapshot) {}

  static restore(snapshot: OrderSnapshot): Order {
    if (!Number.isSafeInteger(snapshot.itemCount) || snapshot.itemCount < 0) {
      throw new OrderRuleError("Cantidad de líneas inválida");
    }

    return new Order({ ...snapshot });
  }

  get id(): string {
    return this.state.id;
  }

  get status(): OrderSnapshot["status"] {
    return this.state.status;
  }

  confirm(): void {
    if (this.state.status === "CONFIRMED") return;

    if (
      this.state.status === "CANCELLED" ||
      this.state.itemCount === 0 ||
      !this.state.paymentConfirmed ||
      !this.state.stockReserved
    ) {
      throw new OrderRuleError("El pedido no puede confirmarse");
    }

    this.state = { ...this.state, status: "CONFIRMED" };
  }

  snapshot(): OrderSnapshot {
    return { ...this.state };
  }
}

Usamos Order como raíz del agregado del ejemplo, sin reconstruir todo su ciclo de vida. restore presupone una representación interna válida en sus tipos; el adaptador real debe validar datos leídos de almacenamiento.

No hay Request, filas SQL ni códigos HTTP. OrderRuleError expresa que no puede cumplirse una regla, no que deba enviarse necesariamente un 409.

La copia del snapshot evita entregar una referencia mutable al estado. No pretende ser un serializador universal del dominio ni el contrato público de la API.

Definir el puerto donde se necesita

La aplicación necesita cargar y guardar Order. Elegimos situar su contrato en Application; otros diseños pueden ubicarlo en Domain cuando responda a sus responsabilidades. La condición importante es que no viva dentro del adaptador técnico.

En sales/application/order-repository.ts:

import type { Order } from "../domain/order.js";

export interface LoadedOrder {
  readonly order: Order;
  readonly revision: number;
}

export interface OrderRepository {
  findById(id: string): Promise<LoadedOrder | null>;
  save(order: Order, expectedRevision: number): Promise<boolean>;
}

El contrato de guardado exige comparar la revisión esperada y aplicar la escritura atómicamente. false representa un conflicto que impidió guardar.

Es una decisión acotada para mostrar concurrencia sin un ORM. No significa que toda aplicación deba utilizar exactamente esta interfaz.

Evita definir un puerto que devuelva SqlRow, un objeto del framework de persistencia o un Response HTTP. La firma también puede filtrar una dependencia aunque el import esté marcado como type.

El caso de uso coordina sin conocer el almacenamiento

En sales/application/confirm-order.ts:

import type { OrderRepository } from "./order-repository.js";

export class OrderNotFoundError extends Error {}
export class OrderConflictError extends Error {}

export class ConfirmOrderUseCase {
  constructor(private readonly orders: OrderRepository) {}

  async execute(input: {
    orderId: string;
  }): Promise<{ orderId: string; status: "CONFIRMED" }> {
    const loaded = await this.orders.findById(input.orderId);

    if (!loaded) throw new OrderNotFoundError();

    if (loaded.order.status !== "CONFIRMED") {
      loaded.order.confirm();

      const saved = await this.orders.save(
        loaded.order,
        loaded.revision,
      );

      if (!saved) throw new OrderConflictError();
    }

    return { orderId: loaded.order.id, status: "CONFIRMED" };
  }
}

El caso de uso conoce el contrato y el modelo. No hace new SqlOrderRepository(), no selecciona conexiones y no devuelve una entidad para serializarla directamente al cliente.

La comprobación de revisión evita perder cambios si la implementación del puerto cumple su garantía. No sustituye todas las reglas de consistencia del proceso.

Dos solicitudes concurrentes podrían producir un éxito y un conflicto; un intento posterior puede observar el pedido confirmado. No prometemos que cualquier repetición concurrente devuelva éxito sin revisar el resultado.

Un adaptador de persistencia sin base de datos

Para concentrarnos en las dependencias, implementamos almacenamiento en memoria. En sales/infrastructure/in-memory-order-repository.ts:

import { Order, type OrderSnapshot } from "../domain/order.js";
import type {
  LoadedOrder,
  OrderRepository,
} from "../application/order-repository.js";

export class InMemoryOrderRepository implements OrderRepository {
  private readonly rows = new Map<string, {
    snapshot: OrderSnapshot;
    revision: number;
  }>();

  constructor(initial: readonly OrderSnapshot[] = []) {
    for (const snapshot of initial) {
      this.rows.set(snapshot.id, {
        snapshot: { ...snapshot },
        revision: 0,
      });
    }
  }

  async findById(id: string): Promise<LoadedOrder | null> {
    const row = this.rows.get(id);
    return row
      ? { order: Order.restore(row.snapshot), revision: row.revision }
      : null;
  }

  async save(order: Order, expectedRevision: number): Promise<boolean> {
    const current = this.rows.get(order.id);

    if (!current || current.revision !== expectedRevision) {
      return false;
    }

    this.rows.set(order.id, {
      snapshot: order.snapshot(),
      revision: current.revision + 1,
    });
    return true;
  }
}

El adaptador conoce el puerto interno y cómo reconstruir el modelo. La aplicación no conoce este Map.

La comparación y escritura no contienen una espera intermedia y sirven para una única instancia en memoria. No es almacenamiento durable ni una solución de concurrencia para varios procesos.

Un adaptador SQL tendría que realizar su comparación y actualización de forma atómica, verificar el resultado y traducir errores y representaciones. No basta con leer una revisión y actualizar después sin protección.

Cambiarlo implica trabajo real de implementación, pruebas y operación. La arquitectura evita que ese detalle redefina las reglas de Order; no vuelve gratuita una migración.

El controlador transforma HTTP a una entrada simple

Utilizamos Express 5 para la entrada. Los errores de handlers asíncronos se propagan al middleware de errores; ese comportamiento debe considerarse si se utiliza otra versión o framework. Express: manejo de errores.

En sales/presentation/http.ts:

import express, {
  type Request,
  type ErrorRequestHandler,
} from "express";
import {
  ConfirmOrderUseCase,
  OrderNotFoundError,
  OrderConflictError,
} from "../application/confirm-order.js";
import { OrderRuleError } from "../domain/order.js";

export class OrderAccessError extends Error {
  constructor(readonly status: 401 | 403) {
    super("Access denied");
  }
}

export type AuthorizeConfirmation = (
  request: Request,
  orderId: string,
) => Promise<void>;

export function createOrderHttpApp(
  confirmOrder: ConfirmOrderUseCase,
  authorize: AuthorizeConfirmation,
) {
  const app = express();
  app.disable("x-powered-by");

  app.post("/orders/:id/confirm", async (req, res) => {
    const orderId = req.params.id;

    if (
      typeof orderId !== "string" ||
      !/^[A-Za-z0-9_-]{1,64}$/.test(orderId)
    ) {
      res.status(400).json({ error: "INVALID_ORDER_ID" });
      return;
    }

    await authorize(req, orderId);
    const output = await confirmOrder.execute({ orderId });
    res.status(200).json(output);
  });

  const errors: ErrorRequestHandler = (error: unknown, _req, res, _next) => {
    if (error instanceof OrderAccessError) {
      res.status(error.status).json({ error: "ACCESS_DENIED" });
      return;
    }

    if (error instanceof OrderNotFoundError) {
      res.status(404).json({ error: "ORDER_NOT_FOUND" });
      return;
    }

    if (
      error instanceof OrderRuleError ||
      error instanceof OrderConflictError
    ) {
      res.status(409).json({ error: "ORDER_CONFIRMATION_CONFLICT" });
      return;
    }

    res.status(500).json({ error: "INTERNAL_ERROR" });
  };

  app.use(errors);
  return app;
}

authorize es una dependencia obligatoria que debe autenticar y comprobar el permiso sobre ese pedido. No se proporciona una implementación ficticia para producción. Si la entrada utiliza cookies, también debe aplicar la protección correspondiente frente a solicitudes cruzadas.

Este tutorial separa el control HTTP para limitar el ejemplo. Si el caso de uso se expone por otras entradas, cada una debe aplicar la política de autorización necesaria; una política de aplicación común puede situarse dentro de Application mediante sus propios contratos.

El cliente no puede marcar pago o reserva como válidos enviando booleanos: la ruta no los acepta como entrada.

Composición manual: conocer detalles en el lugar adecuado

En composition.ts:

import { ConfirmOrderUseCase } from "./sales/application/confirm-order.js";
import { InMemoryOrderRepository } from "./sales/infrastructure/in-memory-order-repository.js";
import {
  createOrderHttpApp,
  type AuthorizeConfirmation,
} from "./sales/presentation/http.js";

export function composeExample(
  authorize: AuthorizeConfirmation,
) {
  const repository = new InMemoryOrderRepository([{
    id: "order-100",
    status: "PENDING",
    itemCount: 2,
    paymentConfirmed: true,
    stockReserved: true,
  }]);

  const confirmOrder = new ConfirmOrderUseCase(repository);
  return createOrderHttpApp(confirmOrder, authorize);
}

La raíz de composición conoce implementaciones concretas porque su responsabilidad es conectarlas. Eso no autoriza al dominio a importarlas de vuelta.

El ejemplo no arranca un servidor ni incluye autenticación o configuración del proyecto. Presupone TypeScript, Node.js, Express 5 y sus tipos disponibles, con compilación ESM adecuada. No es un despliegue listo para producción.

Los archivos mostrados contienen las piezas del recorrido didáctico. No necesitamos Inversify para comprender cómo se conecta una implementación a un contrato.

Recorrer la operación

Con autorización válida, una petición POST /orders/order-100/confirm carga una copia del pedido pendiente, aplica su regla y guarda la nueva revisión.

La respuesta es:

{
  "orderId": "order-100",
  "status": "CONFIRMED"
}

Una lectura posterior del repositorio observa el nuevo estado. En memoria se pierde al reiniciar; el límite se explica, no se oculta con el nombre «persistencia».

Probar sin Express ni base real

Estas pruebas propuestas usan APIs integradas de Node.js y presuponen archivos compilados a JavaScript ESM. No se han ejecutado como parte del artículo.

En confirm-order.test.ts:

import test from "node:test";
import assert from "node:assert/strict";
import { OrderRuleError } from "./sales/domain/order.js";
import { ConfirmOrderUseCase } from "./sales/application/confirm-order.js";
import { InMemoryOrderRepository } from "./sales/infrastructure/in-memory-order-repository.js";

test("confirma y conserva el resultado en el adaptador de pruebas", async () => {
  const repository = new InMemoryOrderRepository([{
    id: "order-100",
    status: "PENDING",
    itemCount: 2,
    paymentConfirmed: true,
    stockReserved: true,
  }]);

  const useCase = new ConfirmOrderUseCase(repository);
  assert.deepEqual(await useCase.execute({ orderId: "order-100" }), {
    orderId: "order-100",
    status: "CONFIRMED",
  });

  assert.equal(
    (await repository.findById("order-100"))?.order.status,
    "CONFIRMED",
  );
});

test("no guarda una confirmación cuando falta el pago", async () => {
  const repository = new InMemoryOrderRepository([{
    id: "order-100",
    status: "PENDING",
    itemCount: 2,
    paymentConfirmed: false,
    stockReserved: true,
  }]);

  const useCase = new ConfirmOrderUseCase(repository);
  await assert.rejects(
    () => useCase.execute({ orderId: "order-100" }),
    OrderRuleError,
  );

  assert.equal(
    (await repository.findById("order-100"))?.order.status,
    "PENDING",
  );
});

Son pruebas del caso de uso con un adaptador controlado. No cubren el transporte, autorización o una base real.

También deben comprobarse cancelación, repetición, pedido inexistente y conflicto de revisión. Un adaptador real necesita su propia verificación de contrato y concurrencia.

La independencia técnica hace posible probar las decisiones sin levantar toda la aplicación. No significa que las pruebas de integración dejen de ser necesarias.

Detectar violaciones antes de que crezcan

Revisa imports y firmas, no solamente carpetas.

Señales concretas:

• Order importa Express o un cliente de base de datos.
• ConfirmOrderUseCase crea directamente el adaptador SQL.
• OrderRepository devuelve filas específicas de un driver.
• El controlador decide que un pedido sin pago puede confirmarse.
• Un caso de uso recibe Request o modifica Response.
• La composición se importa desde el dominio.

TypeScript elimina interfaces al compilar, pero eso no impide que filtren conceptos técnicos durante el diseño. import type no convierte una dependencia incorrecta en correcta.

Las comprobaciones de arquitectura pueden automatizar restricciones de imports. Las revisiones y pruebas siguen siendo necesarias para detectar decisiones mal ubicadas o contratos poco expresivos.

Límites entre contextos y sobreingeniería

Clean Architecture no autoriza a importar el agregado Payments dentro de Sales por ser «dominio». Proteger capas internas y respetar límites entre contextos son condiciones distintas que deben mantenerse juntas.

Si Sales necesita evidencia de otro contexto, su aplicación puede definir un puerto y recibir una traducción mediante ACL HTTP. La llamada no forma parte automáticamente de su transacción local.

Tampoco hace falta repetir todas estas piezas para una operación trivial. Una consulta administrativa pequeña puede utilizar una representación de lectura sin reconstruir un agregado que no aporta comportamiento.

En una plataforma educativa, una regla que permite completar una actividad merece separación de sus detalles de pantalla o almacenamiento. Un listado estático de etiquetas quizá solo necesite una función sencilla.

En reservas, una política de solapamientos puede probarse sin framework. Una exportación acotada de texto puede no necesitar una interfaz para cada transformación.

El nivel de estructura debe responder al valor y complejidad reales. Multiplicar clases delegadoras sin una responsabilidad propia puede hacer más difícil seguir el comportamiento.

Dar a la IA reglas comprobables

Para Cursor, Codex o Claude, especifica qué dependencias están permitidas.

Para implementar:

Trabaja en Sales con Domain sin dependencias de framework. ConfirmOrderUseCase recibe OrderRepository definido en Application. El adaptador implementa ese puerto y la composición se hace manualmente. No importes entidades de otros contextos ni aceptes evidencia financiera desde HTTP.

Para revisar:

Revisa imports, tipos de entrada y salida y creación de dependencias. Señala dónde una política interna conoce Express, SQL o DTOs externos. Propón cambios mínimos y explica qué comportamiento protegen. No evalúes la arquitectura solo por los nombres de carpetas.

Para probar:

Diseña pruebas del caso de uso sin servidor ni base real para confirmación, rechazo y conflicto. Separa esas pruebas de las necesarias para el adaptador de persistencia y autorización. No afirmes que el doble en memoria demuestra durabilidad o concurrencia entre procesos.

Una persona debe confirmar reglas y garantías. Un agente puede respetar el árbol de carpetas y seguir colocando la decisión comercial en el lugar equivocado.

Ejercicios

1. La interfaz colocada afuera

OrderRepository vive junto al cliente SQL y Application la importa desde allí. ¿Qué revisarías?

2. El tipo HTTP conveniente

El caso de uso acepta Request para leer un encabezado y ahorrar un objeto de entrada. ¿Qué dependencia introduce?

3. Más carpetas, misma decisión

El controlador llama a un servicio que confirma cualquier pedido y luego comprueba el pago antes de enviar la respuesta. ¿Se ha protegido la regla?

Soluciones razonadas

1. Quién define la necesidad. Si el puerto pertenece a la aplicación, debe poder existir sin conocer el adaptador técnico. Mover el contrato y eliminar tipos del driver puede invertir correctamente la dependencia.

2. El caso de uso queda vinculado al transporte y a sus tipos. La entrada debe traducir lo necesario a una representación propia, o utilizar un contrato de aplicación para la capacidad requerida.

3. No. La regla se comprueba después y sigue fuera del comportamiento protegido. La confirmación no debe persistirse antes de evaluar sus condiciones. Cambiar nombres de archivos no corrige el orden ni la responsabilidad.

Proteger políticas mediante decisiones visibles

Clean Architecture complementa al modelado cuando las reglas pueden entenderse y probarse sin depender de cómo entra una petición o dónde se guardan los datos.

La evidencia está en las dependencias, los contratos y las pruebas, no en reproducir un diagrama de círculos.

Empieza por una regla relevante y un límite claro. Añade las piezas que permiten sostenerlos, conservando explícitas las garantías que el ejemplo todavía no implementa.