Domain-Driven Design: Layered Architecture para organizar el código y separar responsabilidades

Una tienda tiene un endpoint para confirmar pedidos. El controlador valida el JSON, consulta la base de datos, comprueba que haya artículos, cambia el estado y devuelve una respuesta. Todo funciona hasta que otra integración necesita confirmar pedidos sin pasar por HTTP.

El equipo copia las comprobaciones. Más tarde cambia una regla y solo actualiza uno de los dos recorridos. Ahora un pedido vacío se rechaza desde el panel, pero se confirma desde la integración.

El problema no es la cantidad de líneas del controlador. Es que las reglas, la coordinación y los detalles técnicos están mezclados. Layered Architecture permite distribuir esas responsabilidades y establecer cómo colaboran, de modo que una nueva entrada no necesite reconstruir el comportamiento del negocio.

Qué organiza Layered Architecture

Una layer agrupa responsabilidades relacionadas y define qué servicios ofrece a otras partes del sistema. En DDD se distinguen tradicionalmente Presentation, también llamada User Interface, Application, Domain e Infrastructure. El propósito central es aislar el modelo y sus reglas de los detalles de interfaz y soporte técnico. Evans desarrolla esta separación en la sección Layered Architecture de su referencia de DDD.

Son separaciones del código, no necesariamente procesos o servidores distintos. Puedes mantener las cuatro layers en una sola aplicación Node.js y desplegarla como una unidad. Tampoco corresponden a etapas que cada dato deba recorrer obligatoriamente: leer un listado puede requerir un recorrido distinto de ejecutar una operación con reglas.

Presentation: adaptar la interacción

Presentation recibe entradas y presenta resultados. En un backend HTTP, incluye rutas y controladores: interpreta parámetros, valida la forma de la petición y selecciona la respuesta HTTP. No decide si un pedido puede confirmarse.

Application: coordinar una operación

Application implementa los Use Cases, las operaciones que ofrece el sistema. Recupera información, invoca comportamiento del Domain y coordina el guardado. Puede establecer el límite de una transacción local, cuando la operación lo requiere. No necesita conocer Request, Response ni sentencias SQL.

Domain: decidir según las reglas

Domain expresa conceptos y comportamiento del negocio. En nuestro ejemplo decide si un pedido puede confirmarse. Esa regla debe seguir aplicándose aunque la operación provenga de HTTP, una tarea programada o una prueba.

Infrastructure: resolver mecanismos técnicos

Infrastructure implementa acceso a almacenamiento y servicios externos. Sabe ejecutar una consulta o una petición HTTP; no debe convertirse en el único lugar donde se decide si el negocio permite una acción.

La ubicación exacta de algunos contratos puede variar. Lo importante es poder explicar qué decisión corresponde a cada responsabilidad y qué dependencias introduce tu elección.

Una llamada no es lo mismo que una dependencia

Al ejecutar un Use Case, Application necesita recuperar datos. Eso no obliga a importar directamente un cliente de base de datos.

En este artículo elegiremos un contrato de Repository definido en Domain y una implementación en Infrastructure. Un Repository ofrece recuperar y guardar el modelo; no profundizaremos aquí en ese patrón. Application conoce el contrato y recibe una implementación desde fuera.

El flujo de ejecución será:

Petición HTTP
  -> Presentation: validar y adaptar
  -> Application: coordinar ConfirmOrder
       -> Infrastructure: cargar mediante el contrato de Repository
       -> Domain: ejecutar Order.confirm()
       -> Infrastructure: guardar mediante el mismo contrato
  <- Presentation: traducir el resultado a HTTP

Las dependencias del código serán diferentes:

Presentation   -> Application
Application    -> Domain
Infrastructure -> Domain

server.ts conecta las implementaciones concretas.
Domain no importa Express, Application ni Infrastructure.

Una flecha del segundo diagrama significa «importa o conoce tipos definidos en». Infrastructure implementa un contrato de Domain; Application puede invocar esa implementación durante la ejecución sin importar su clase concreta. Esto se conoce como Dependency Inversion.

Esta es la variante elegida para aislar el Domain en el ejemplo. Layered Architecture no determina por sí sola un único grafo de imports. Algunas organizaciones usan dependencias descendentes más directas; otras invierten dependencias técnicas. Por eso «tenemos cuatro carpetas» no describe todavía las reglas arquitectónicas.

Antes: todas las decisiones en una ruta

Este fragmento parcial utiliza un objeto database ficticio. Ilustra el problema; no es un servidor ejecutable:

app.patch('/orders/:orderId/confirmation', async (req, res) => {
  const row = await database.findOrder(req.params.orderId);
  if (!row) return res.status(404).json({ error: 'Pedido inexistente' });
  if (row.itemCount === 0 || row.status === 'cancelled') {
    return res.status(409).json({ error: 'No se puede confirmar' });
  }
  await database.updateOrder(row.id, { status: 'confirmed' });
  return res.json({ id: row.id, status: 'confirmed' });
});

La regla solo existe dentro de esa ruta. Probarla exige atravesar Express o extraerla artificialmente. Cambiar el almacenamiento también afecta al controlador.

La transformación será progresiva: extraer la regla, crear un Use Case, introducir el contrato de persistencia y dejar en la ruta únicamente la adaptación HTTP. Cada paso debe conservar o comprobar el comportamiento esperado.

Ejemplo completo: confirmar un pedido

Contrato y límites de la demostración

Nuestra operación acepta esta petición:

PATCH /orders/order-1/confirmation
Content-Type: application/json

{}

Las reglas elegidas son sencillas: un pedido vacío o cancelado no puede confirmarse. Confirmar de nuevo un pedido ya confirmado devuelve su estado sin crear otro efecto. No modelaremos pagos, stock ni notificaciones.

La validación se reparte por propósito. Presentation exige un objeto vacío; Domain comprueba las condiciones del pedido; Application distingue un identificador inexistente de una operación rechazada. Un formato JSON correcto no implica una acción válida para el negocio.

El siguiente proyecto didáctico incluye todos sus archivos. Usa Node.js 24.21.0 y Express 4.x. El almacenamiento en memoria representa Infrastructure, pero no conserva datos al reiniciar ni ofrece coordinación entre procesos. No incluye autenticación: escucha solo en la interfaz local y no debe exponerse como servicio real sin controles de acceso.

Estructura y preparación

layered-example/
  package.json
  domain/
    order.ts
    order-repository.ts
  application/
    confirm-order.ts
  infrastructure/
    memory-order-repository.ts
  presentation/
    app.ts
  server.ts
  example.test.ts

Crea package.json con este contenido:

{
  "name": "layered-example",
  "private": true,
  "type": "module"
}

Desde esa carpeta, instala Express siguiendo su procedimiento oficial de instalación, seleccionando la versión principal usada aquí:

npm install express@4

Node.js ejecuta directamente la sintaxis TypeScript utilizada a continuación mediante type stripping, que elimina anotaciones de tipos. Esto no realiza comprobación estática de tipos. Para comprobar tipos con tsc necesitarías configurar TypeScript y sus declaraciones correspondientes; este tutorial se limita a ejecución y pruebas de comportamiento.

1. Domain protege la regla

Archivo domain/order.ts:

export type OrderSnapshot = {
  id: string;
  itemCount: number;
  status: 'draft' | 'confirmed' | 'cancelled';
};

export class OrderRuleError extends Error {}

export class Order {
  #state: OrderSnapshot;

  constructor(state: OrderSnapshot) {
    if (!Number.isSafeInteger(state.itemCount) || state.itemCount < 0) {
      throw new OrderRuleError('Cantidad de artículos inválida');
    }
    if (state.status === 'confirmed' && state.itemCount === 0) {
      throw new OrderRuleError('Un pedido confirmado no puede estar vacío');
    }
    this.#state = { ...state };
  }

  confirm(): void {
    if (this.#state.status === 'cancelled') {
      throw new OrderRuleError('Un pedido cancelado no puede confirmarse');
    }
    if (this.#state.itemCount === 0) {
      throw new OrderRuleError('Un pedido vacío no puede confirmarse');
    }
    this.#state.status = 'confirmed';
  }

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

El constructor recibe datos confiables de nuestra demostración. Si procedieran de almacenamiento externo, el adaptador tendría que validar también su estructura y los valores admitidos antes de reconstruir el modelo. Los tipos no validan datos en tiempo de ejecución.

Archivo domain/order-repository.ts:

import type { Order } from './order.ts';

export interface OrderRepository {
  find(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

El contrato no menciona tablas, conexiones ni HTTP. Tampoco convierte todo fallo de almacenamiento en un rechazo de negocio.

2. Application coordina sin conocer Express

Archivo application/confirm-order.ts:

import { OrderRuleError, type OrderSnapshot } from '../domain/order.ts';
import type { OrderRepository } from '../domain/order-repository.ts';

export type ConfirmationResult =
  | { kind: 'not_found' }
  | { kind: 'rejected'; reason: string }
  | { kind: 'confirmed'; order: OrderSnapshot };

export class ConfirmOrder {
  #orders: OrderRepository;

  constructor(orders: OrderRepository) {
    this.#orders = orders;
  }

  async execute(orderId: string): Promise<ConfirmationResult> {
    const order = await this.#orders.find(orderId);
    if (!order) return { kind: 'not_found' };

    try {
      order.confirm();
    } catch (error) {
      if (error instanceof OrderRuleError) {
        return { kind: 'rejected', reason: error.message };
      }
      throw error;
    }

    await this.#orders.save(order);
    return { kind: 'confirmed', order: order.snapshot() };
  }
}

Application transforma un rechazo conocido en un resultado explícito. No responde 409: ese código pertenece a HTTP. Un fallo inesperado de persistencia se propaga; no se presenta como si el pedido hubiera incumplido una regla.

3. Infrastructure implementa el almacenamiento

Archivo infrastructure/memory-order-repository.ts:

import { Order, type OrderSnapshot } from '../domain/order.ts';
import type { OrderRepository } from '../domain/order-repository.ts';

export class MemoryOrderRepository implements OrderRepository {
  #rows = new Map<string, OrderSnapshot>();

  constructor(initial: OrderSnapshot[]) {
    for (const state of initial) {
      const validated = new Order(state).snapshot();
      this.#rows.set(validated.id, validated);
    }
  }

  async find(id: string): Promise<Order | null> {
    const state = this.#rows.get(id);
    return state ? new Order(state) : null;
  }

  async save(order: Order): Promise<void> {
    const state = order.snapshot();
    this.#rows.set(state.id, state);
  }
}

Guardar copias evita que modificar un objeto recuperado cambie el almacenamiento antes de llamar a save. Cambiar esta implementación por SQL no debería obligar a reescribir Order.confirm().

Eso no significa que cualquier sustitución sea automática: la implementación real debe sostener el contrato, tratar fallos y proteger conflictos entre escrituras. Este Repository en memoria no demuestra esas garantías.

4. Presentation valida y traduce a HTTP

Archivo presentation/app.ts:

import express from 'express';
import type { ErrorRequestHandler } from 'express';
import type { ConfirmOrder } from '../application/confirm-order.ts';

export function createApp(confirmOrder: ConfirmOrder) {
  const app = express();
  app.use(express.json({ limit: '1kb' }));

  app.patch('/orders/:orderId/confirmation', async (req, res, next) => {
    try {
      const body: unknown = req.body;
      if (
        typeof body !== 'object' || body === null || Array.isArray(body) ||
        Object.keys(body).length !== 0
      ) {
        res.status(400).json({ error: 'Se esperaba un objeto vacío' });
        return;
      }

      const result = await confirmOrder.execute(req.params.orderId);
      if (result.kind === 'not_found') {
        res.status(404).json({ error: 'Pedido inexistente' });
      } else if (result.kind === 'rejected') {
        res.status(409).json({ error: result.reason });
      } else {
        res.status(200).json({ id: result.order.id, status: result.order.status });
      }
    } catch (error) {
      next(error);
    }
  });

  const handleError: ErrorRequestHandler = (error, _req, res, _next) => {
    if (error.type === 'entity.parse.failed') {
      res.status(400).json({ error: 'JSON inválido' });
    } else if (error.type === 'entity.too.large') {
      res.status(413).json({ error: 'Petición demasiado grande' });
    } else {
      res.status(500).json({ error: 'Error interno' });
    }
  };
  app.use(handleError);
  return app;
}

La ruta valida la forma de la entrada, pero no vuelve a contar artículos. El mapeo HTTP está definido en un único lugar. Usamos try/catch y next(error) porque en Express 4 los rechazos asíncronos necesitan propagarse explícitamente al error handler; la documentación de Express distingue este comportamiento del de Express 5.

5. Conectar las piezas y observar la respuesta

Archivo server.ts:

import { ConfirmOrder } from './application/confirm-order.ts';
import { MemoryOrderRepository } from './infrastructure/memory-order-repository.ts';
import { createApp } from './presentation/app.ts';

const orders = new MemoryOrderRepository([
  { id: 'order-1', itemCount: 2, status: 'draft' },
  { id: 'order-empty', itemCount: 0, status: 'draft' },
]);

const confirmOrder = new ConfirmOrder(orders);
const app = createApp(confirmOrder);
app.listen(3000, '127.0.0.1', () => {
  console.log('Servidor disponible en http://127.0.0.1:3000');
});

Este punto de ensamblaje se llama Composition Root: conoce las implementaciones concretas y las conecta. Pasarlas por el constructor es Dependency Injection; no requiere un framework.

Ejecuta el servidor:

node server.ts

Desde otra terminal puedes enviar la petición. En Windows usa curl.exe si curl corresponde a un alias de PowerShell:

curl --request PATCH http://127.0.0.1:3000/orders/order-1/confirmation --header "Content-Type: application/json" --data "{}"

La respuesta es 200 con este cuerpo:

{"id":"order-1","status":"confirmed"}

Con order-empty obtendrás 409; con un identificador inexistente, 404. Repetir la confirmación de order-1 mantiene confirmed. Esta repetición no crea otro efecto en el ejemplo; si añades cobros o notificaciones, tendrás que diseñar explícitamente cómo evitar efectos duplicados.

Pruebas que muestran para qué sirve la separación

Archivo example.test.ts:

import assert from 'node:assert/strict';
import { once } from 'node:events';
import test from 'node:test';
import { Order } from './domain/order.ts';
import { ConfirmOrder } from './application/confirm-order.ts';
import { MemoryOrderRepository } from './infrastructure/memory-order-repository.ts';
import { createApp } from './presentation/app.ts';

test('Domain rechaza un pedido vacío sin cambiar su estado', () => {
  const order = new Order({ id: 'empty', itemCount: 0, status: 'draft' });
  assert.throws(() => order.confirm(), /vacío/);
  assert.equal(order.snapshot().status, 'draft');
});

test('Application confirma y guarda sin servidor HTTP', async () => {
  const orders = new MemoryOrderRepository([
    { id: 'ready', itemCount: 1, status: 'draft' },
    { id: 'cancelled', itemCount: 1, status: 'cancelled' },
  ]);
  const useCase = new ConfirmOrder(orders);
  assert.equal((await useCase.execute('ready')).kind, 'confirmed');
  assert.equal((await orders.find('ready'))?.snapshot().status, 'confirmed');
  assert.equal((await useCase.execute('ready')).kind, 'confirmed');
  assert.equal((await useCase.execute('missing')).kind, 'not_found');
  assert.equal((await useCase.execute('cancelled')).kind, 'rejected');
});

test('Presentation valida la entrada y traduce resultados a HTTP', async () => {
  const orders = new MemoryOrderRepository([
    { id: 'ready', itemCount: 1, status: 'draft' },
    { id: 'empty', itemCount: 0, status: 'draft' },
  ]);
  const server = createApp(new ConfirmOrder(orders)).listen(0, '127.0.0.1');
  try {
    await once(server, 'listening');
    const address = server.address();
    if (!address || typeof address === 'string') throw new Error('Puerto no disponible');
    const base = `http://127.0.0.1:${address.port}/orders`;
    const send = (id: string, body: string) => fetch(`${base}/${id}/confirmation`, {
      method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body,
    });

    assert.equal((await send('ready', '{')).status, 400);
    assert.equal((await send('ready', '{"status":"confirmed"}')).status, 400);
    assert.equal((await send('missing', '{}')).status, 404);
    assert.equal((await send('empty', '{}')).status, 409);
    const response = await send('ready', '{}');
    assert.equal(response.status, 200);
    assert.deepEqual(await response.json(), { id: 'ready', status: 'confirmed' });
  } finally {
    await new Promise<void>((resolve, reject) => {
      server.close(error => error ? reject(error) : resolve());
    });
  }
});

Ejecuta las pruebas con:

node --test example.test.ts

La primera comprueba una regla sin Express ni almacenamiento. La segunda comprueba coordinación y guardado sin HTTP. La tercera recorre el endpoint con el adaptador en memoria. Las tres pruebas se ejecutaron y pasaron con Node.js 24.21.0 y Express 4.22.3. No se realizó comprobación estática con TypeScript ni una prueba contra una base de datos real: al introducirla, necesitarás comprobar también su integración.

La separación no reduce por sí sola el número de errores. Permite localizar decisiones y comprobarlas con dependencias proporcionales a cada prueba.

Otros escenarios: qué cambia y qué se reutiliza

Educación: el mismo Use Case desde una tarea programada

Una academia habilita certificados desde un endpoint y desde una tarea nocturna. Presentation adapta la petición web; la tarea constituye otra entrada. Ambas pueden invocar el mismo Use Case, que obtiene la evidencia y pide al Domain decidir si corresponde emitir.

El aprendizaje aquí es separar entrada de operación. La tarea no debe fabricar un objeto Request para reutilizar la ruta. Tampoco debe copiar la regla de aprobación. El Use Case recibe los datos que necesita, no objetos del framework.

Logística: sustituir una integración sin copiar su modelo

Un proveedor representa entregas con códigos externos. Infrastructure implementa una Anticorruption Layer, o ACL, que valida su respuesta HTTP y la traduce al contrato que necesita el consumidor. Application coordina la consulta; Domain evalúa qué significa esa evidencia para el proceso propio.

Si el proveedor no responde, no conviertas el fallo en «entrega pendiente» como si fuera un hecho confirmado. El contrato debe distinguir ausencia de evidencia e indisponibilidad técnica.

Este caso enseña a separar traducción e interpretación del negocio. Si hay varios Bounded Contexts, límites donde cada modelo mantiene un significado consistente, cada uno conserva sus implementaciones: la integración del ejemplo ocurre por ACL HTTP con contratos del consumidor, sin importaciones entre contextos. HTTP no comparte la transacción local del Repository.

Cómo refactorizar sin trasladar la mezcla a otras carpetas

Empieza por escenarios que describan el comportamiento actual y las reglas acordadas. Extrae una regla concreta hacia Domain y haz que la ruta la invoque. Después introduce Application para coordinar carga, operación y guardado. Finalmente separa los detalles de almacenamiento y conecta las implementaciones en el Composition Root.

Mover un controlador entero a application/service.ts conserva la mezcla si sigue usando req, res y SQL. Del mismo modo, un Domain que importa Express para lanzar errores HTTP mantiene una dependencia del transporte aunque esté en otra carpeta.

Define reglas de imports que puedas revisar. En el ejemplo, Domain no importa otras layers; Application no importa Express ni implementaciones de Infrastructure. Puedes empezar comprobándolo en revisión y automatizarlo cuando el tamaño del proyecto lo justifique.

Layered, Hexagonal, Onion y Clean Architecture

Comparten objetivos de separación, pero destacan criterios distintos:

• Layered Architecture organiza responsabilidades en layers y define cómo colaboran. El aislamiento concreto depende también de sus reglas de dependencias.
• Hexagonal Architecture, descrita por Alistair Cockburn, distingue el interior de la aplicación de sus interacciones externas mediante ports y adapters: contratos de interacción e implementaciones que conectan tecnologías concretas.
• Onion Architecture, presentada por Jeffrey Palermo, coloca el modelo en el centro y dirige las dependencias hacia el interior, dejando detalles técnicos fuera.
• Clean Architecture, explicada por Robert C. Martin, separa políticas y detalles mediante límites y una regla de dependencias hacia las políticas internas.

Nuestro contrato de Repository y el ensamblaje externo son compatibles con varias de estas ideas. No convierten automáticamente el proyecto en una implementación completa de todas ellas. Para discutir el diseño, resulta más útil mostrar responsabilidades e imports permitidos que elegir una etiqueta.

Cuándo conviene mantenerlo más simple

Un catálogo interno con dos campos y operaciones CRUD —crear, consultar, actualizar y eliminar— puede resolverse con una ruta pequeña, validación y acceso a datos claramente separado. Crear una clase que solo reenvíe cada llamada a otra clase aporta poco si no existe una responsabilidad distinta.

Layered Architecture implica archivos, contratos y decisiones de ensamblaje. Ese coste se justifica cuando necesitas proteger reglas, reutilizar operaciones o aislar tecnologías. No obliga a utilizar un modelo con comportamiento para cada lectura ni un Repository genérico para todas las tablas.

Prompts para orientar y revisar trabajo con IA

Analizar responsabilidades mezcladas

Analiza este controlador de confirmación. Clasifica validación HTTP, coordinación, reglas del pedido y persistencia. No cambies archivos. Devuelve evidencias y una propuesta mínima de extracción que conserve las respuestas actuales. No añadas frameworks ni reglas de negocio. Una persona confirmará las reglas y revisará qué escenarios deben protegerse antes de refactorizar.

Implementar una separación acotada

Refactoriza la operación con Presentation, Application, Domain e Infrastructure. Domain no importa Express ni infraestructura; Application depende del contrato de Repository; la implementación concreta se conecta fuera. Mantén el formato de respuesta acordado. No añadas autenticación, colas ni nuevas dependencias al alcance. Entrega el cambio y pruebas de pedido vacío, cancelado y confirmación repetida. Una persona ejecutará las pruebas y revisará la conservación del contrato HTTP.

Revisar límites y garantías

Revisa el diff contra estas reglas de imports y responsabilidades. Busca lógica duplicada en Presentation, HTTP en Domain, implementaciones técnicas importadas desde Application y supuestos de transacción compartida por HTTP. No edites archivos. Reporta cada hallazgo con evidencia y efecto observable; separa dudas de incumplimientos. Una persona verificará las garantías del almacenamiento y los escenarios concurrentes que el ejemplo en memoria no cubre.

Un buen prompt puede hacer explícitos los límites. La revisión humana debe comprobar que esos límites existen en el código y que la conducta sigue siendo la acordada; una estructura de carpetas convincente no demuestra ninguna de las dos cosas.

Tres ejercicios con solución razonada

1. Cambiar el error HTTP

El producto quiere responder 422 en lugar de 409 cuando no se puede confirmar. ¿Debe cambiar Order.confirm()?

Solución razonada: en el diseño del ejemplo cambia Presentation, donde se traduce rejected. Domain conserva la regla y Application su resultado. Las pruebas HTTP se actualizan para el contrato nuevo; las de la regla deberían seguir pasando. Cambiar una respuesta pública requiere acordar su impacto con consumidores.

2. Reutilizar una confirmación desde una importación

Una importación administrativa propone llamar al controlador simulando req y res. ¿Qué alternativa usarías?

Solución razonada: que la entrada de importación valide su propio formato e invoque ConfirmOrder.execute. Así reutiliza coordinación y reglas sin depender del transporte HTTP. Si necesita permisos o límites propios, deben definirse explícitamente; reutilizar el Use Case no equivale a autorizar cualquier llamada.

3. Dos personas editan el mismo pedido

Una confirma y otra cancela basándose en el mismo estado leído. El equipo afirma que las layers evitan el conflicto. ¿Es suficiente?

Solución razonada: no. La separación no coordina escrituras. Hay que definir el resultado permitido y aplicar control de concurrencia en la persistencia, por ejemplo mediante versión y escritura condicionada dentro de una transacción local. El Use Case debe tratar el conflicto; la prueba necesita reproducirlo contra el almacenamiento correspondiente.

Cómo reconocer una separación útil

Comprueba si puedes explicar quién recibe la entrada, quién coordina, quién decide y quién resuelve el acceso técnico. Después verifica si una regla puede probarse sin servidor y si otra entrada puede ejecutar el Use Case sin copiar comportamiento.

Cuando esas respuestas coinciden con los imports y las pruebas, las layers están aportando una separación real. Si solo cambian los nombres de las carpetas, vuelve a una operación concreta y revisa sus responsabilidades: ahí empieza una organización del código que puedes mantener y comprobar.