DEV Community: Carlos Martínez

Implementando DDD y Arquitectura Hexagonal en NestJS: Una Guía Práctica Completa

Carlos Martínez — Wed, 21 Oct 2026 04:02:26 +0000

1. Cuando un servicio empieza a hacerlo todo

Una aplicación NestJS suele comenzar con un controlador, un servicio y unas cuantas llamadas a Prisma. Esa estructura es fácil de entender cuando la operación de negocio consiste en “guardar estos campos”. Después cambian los requisitos.

Una orden necesita un técnico antes de registrar trabajo. Las tareas obligatorias deben completarse antes de finalizarla. Una visita tiene que encajar en la agenda del técnico. Cerrar una orden debe registrar un evento de negocio junto con el estado actualizado.

Cuando todas esas decisiones viven en servicios que también manejan respuestas HTTP y registros de la base de datos, cambiar una regla implica recorrer varias responsabilidades técnicas. Probarla puede requerir construir mucha más aplicación de la que esa regla necesita.

En esta guía recorreremos una API de gestión de servicios construida con TypeScript, NestJS, Prisma y PostgreSQL. Usaremos Domain-Driven Design (DDD, o diseño guiado por el dominio) para expresar el comportamiento del negocio y Arquitectura Hexagonal para controlar sus dependencias.

Conviene conocer clases, interfaces, funciones asíncronas de TypeScript y controladores básicos de NestJS. No necesitas experiencia previa con DDD. El objetivo es entender dónde pertenece cada responsabilidad y cómo se conectan las piezas.

El ejemplo completo está disponible en nest-ddd-hexagonal en GitHub. Los fragmentos siguientes provienen del proyecto; cuando se indica, se omiten imports o código ajeno a la explicación. Es una implementación educativa con límites concretos que analizaremos junto con sus ventajas.

2. Empieza por el negocio y su lenguaje

Imagina una empresa que envía técnicos a las instalaciones de sus clientes. Una orden de servicio representa el trabajo comprometido: cliente, contrato, dirección, nivel de servicio, tareas obligatorias, actividades realizadas y materiales utilizados. Una visita representa una cita programada con un técnico.

El proyecto organiza esas responsabilidades en dos módulos:

Módulo	Conceptos principales	Responsabilidades
`service-orders`	`ServiceOrder`, actividades, materiales, tareas obligatorias	Registrar trabajo, proteger el ciclo de vida, finalizar y cerrar órdenes
`visits`	`Technician`, `Visit`, `TimeSlot`, `TechnicianAvailability`	Registrar técnicos, programar visitas, comprobar disponibilidad y cancelar citas

Estos módulos son posibles límites de contexto dentro de un monolito modular. Se ejecutan en el mismo proceso y comparten PostgreSQL, mientras mantienen modelos y contratos de aplicación separados. Una carpeta por sí sola no establece un contexto delimitado: el límite útil surge de la propiedad sobre el lenguaje, las reglas y la integración.

Varios requisitos hacen que este ejemplo vaya más allá de un CRUD básico:

El nivel de servicio determina la prioridad de la orden.
Debe existir un técnico asignado antes de registrar actividades o materiales.
Finalizar requiere al menos una actividad y ninguna tarea obligatoria pendiente.
Cerrar requiere una finalización previa y registra un evento de dominio.
Las visitas duran entre 30 minutos y cuatro horas y no pueden comenzar en el pasado.
La programación comprueba si el técnico está activo, si hay solapamientos y si el estado y la asignación de la orden permiten la visita.

DDD nos ayuda a convertir esas frases en operaciones con nombre. order.finalize() comunica una decisión de negocio de forma más directa que asignar un campo de estado en un controlador HTTP. Esos nombres también proporcionan un vocabulario útil para las pruebas.

3. Las dependencias apuntan hacia el núcleo

En el artículo original de Arquitectura Hexagonal de Alistair Cockburn, la aplicación puede ejecutarse y probarse de forma independiente de sus interfaces externas. Los puertos describen interacciones con la aplicación; los adaptadores las conectan con tecnologías concretas.

Este repositorio implementa esa idea mediante tres capas:

Capa	Responsabilidad	Dependencias
Dominio	Conceptos del negocio, invariantes, comportamiento y errores de dominio	Su propio modelo y APIs estándar del entorno de ejecución
Aplicación	Casos de uso y contratos para capacidades externas	Dominio y puertos de aplicación
Infraestructura	HTTP, validación de DTOs, persistencia y adaptadores de integración	Aplicación, dominio y bibliotecas técnicas

El núcleo está formado por dominio y aplicación. En este proyecto, ninguna de esas capas importa NestJS ni Prisma. Sí utilizan APIs estándar de Node.js como randomUUID: la independencia del framework no implica independencia de todo entorno de ejecución.

Las siguientes flechas representan dependencias en el código fuente:

Controlador HTTP ----------> Caso de uso ----------> Modelo de dominio
                                 |
                                 v
                          Puerto de aplicación
                                 ^
                                 |
Adaptador Prisma ----------------+
       |
       v
Cliente Prisma / PostgreSQL

Módulo Nest: selecciona adaptadores y construye casos de uso

Durante la ejecución, el caso de uso invoca un adaptador a través del puerto. La dirección de dependencias sigue apuntando hacia dentro porque el caso de uso importa la interfaz y el adaptador implementa esa interfaz.

El repositorio coloca los puertos de salida en application/ports, donde los consumen los casos de uso. Ubicarlos en el dominio también puede ser razonable cuando esa capa es dueña del contrato. La Arquitectura Hexagonal no exige una ubicación universal de carpetas.

Las operaciones de entrada se exponen mediante los métodos de los casos de uso. Los controladores los llaman directamente; no existe una interfaz adicional para cada puerto de entrada. Lo importante es que el núcleo pueda ejecutarse de forma independiente de HTTP y de la persistencia.

4. Organiza por capacidad y después por capa

Esta es una vista abreviada del proyecto:

src/
├── main.ts
├── app.module.ts
├── shared/
│   ├── domain/
│   └── infrastructure/
└── modules/
    ├── service-orders/
    │   ├── domain/
    │   │   ├── model/
    │   │   ├── events/
    │   │   └── errors/
    │   ├── application/
    │   │   ├── ports/
    │   │   └── use-cases/
    │   ├── infrastructure/
    │   │   ├── http/
    │   │   └── persistence/
    │   └── service-orders.module.ts
    └── visits/
        ├── domain/
        ├── application/
        ├── infrastructure/
        │   ├── http/
        │   ├── persistence/
        │   └── integration/
        └── visits.module.ts

prisma/    # Esquema y migraciones SQL
test/      # Pruebas de dominio, aplicación, HTTP y adaptadores

Agrupar por capacidad de negocio mantiene cerca el trabajo relacionado. Dentro de cada módulo, las tres capas explican sus responsabilidades. Esto sigue la organización por funcionalidad que suele asociarse con vertical slicing o corte vertical, aunque el repositorio conserva capas explícitas dentro de cada módulo.

El resultado es más fácil de recorrer que carpetas globales con todos los controladores, servicios y entidades. Eso no vuelve automáticamente independientes a los módulos: visits se integra con service-orders, así que extraer uno todavía requeriría resolver esa integración y la base de datos compartida.

El directorio compartido contiene mecanismos pequeños como DomainError, DomainEvent y AggregateRoot, además del soporte de infraestructura. Los modelos de negocio permanecen en los módulos que los poseen. Un repositorio genérico compartido aportaría poco cuando cada módulo tiene necesidades de persistencia diferentes.

5. Modela las reglas dentro del dominio

5.1 Un agregado protege un límite de consistencia

ServiceOrder es la raíz del agregado que contiene la orden y sus colecciones hijas. El código modifica la orden mediante operaciones como assignTechnician, addActivity, completeRequiredTask, finalize y close.

Un agregado define un límite dentro del cual se administran juntos el estado relacionado y sus reglas. En esta implementación, el repositorio persiste la raíz, las actividades, los materiales y las tareas obligatorias como una instantánea transaccional.

El ciclo de vida principal es:

CREATED -> ASSIGNED -> IN_PROGRESS -> FINALIZED -> CLOSED
             ^              |
             |              +-- las actividades o materiales inician el trabajo
             +-- se puede cambiar el técnico antes de iniciar el trabajo

Finalizar también requiere:
  técnico asignado + al menos una actividad + todas las tareas completadas

La implementación del agregado tiene un constructor privado y fábricas separadas para creación y rehidratación. La creación deriva la prioridad a partir del nivel de servicio y comienza la orden en CREATED. La rehidratación reconstruye una orden existente y valida la consistencia de la instantánea sin volver a ejecutar las operaciones del negocio.

Este es el método finalize real, sin el resto de la clase:

finalize(now = new Date()): void {
  this.ensureOperationallyMutable();
  this.ensureTechnicianAssigned();

  if (this.activitiesValue.length === 0) throw new ActivityRequiredError();

  const pending = this.requiredTasksValue
    .filter((task) => !task.completedAt)
    .map((task) => task.id);
  if (pending.length > 0) throw new PendingRequiredTasksError(pending);

  if (this.statusValue !== ServiceOrderStatus.IN_PROGRESS) {
    throw new ServiceOrderInvalidStateError(
      `Only an in-progress service order can be finalized; current state is ${this.statusValue}`,
    );
  }

  const latestWork = Math.max(
    this.createdAtValue.getTime(),
    ...this.activitiesValue.map((activity) => activity.performedAt.getTime()),
    ...this.requiredTasksValue.map((task) => task.completedAt?.getTime() ?? 0),
  );
  const finalizedAt = validDate(now, 'finalizedAt', new Date(latestWork));
  this.statusValue = ServiceOrderStatus.FINALIZED;
  this.finalizedAtValue = finalizedAt;
}

La operación valida sus condiciones antes de cambiar el estado. Registrar solamente material mueve una orden asignada a trabajo en progreso, pero sigue sin satisfacer el requisito de contar con una actividad para finalizar. La fecha también debe ser coherente con el trabajo registrado.

Estas reglas se aplican tanto si el modelo lo invoca un controlador como una prueba o un futuro adaptador para procesamiento por lotes. Conservan su significado sin conocer códigos HTTP ni columnas de base de datos.

5.2 Encapsular también implica proteger referencias

El agregado es mutable a través de sus métodos. Sus getters devuelven instantáneas congeladas de los elementos hijos y copias de las fechas, evitando que un consumidor modifique indirectamente las colecciones internas.

Ese detalle importa en JavaScript: readonly es una restricción de compilación, y un Date puede cambiar aunque la propiedad que lo contiene no permita reasignación. Copiar las fechas al recibirlas y devolverlas protege al agregado de esas mutaciones por referencia.

La implementación también valida metadatos rehidratados, identificadores de los elementos hijos, fechas del ciclo de vida y consistencia del estado. Es una decisión de seguridad deliberada que añade trabajo de validación. Los datos persistidos también atraviesan una frontera y deben convertirse en un modelo válido.

5.3 Un objeto de valor da significado a los intervalos

Technician y Visit son entidades: conservan su identidad mientras cambia su estado. TimeSlot es un objeto de valor: describe un intervalo mediante sus valores, sin un identificador ni un ciclo de vida propios. Su función es representar un intervalo válido y responder preguntas sobre él. El código completo incluye funciones auxiliares para validar fechas y calcular duraciones; este fragmento contiene su comportamiento principal:

export class TimeSlot {
  private constructor(
    private readonly startsAtValue: Date,
    private readonly endsAtValue: Date,
  ) {}

  static create(startsAt: Date, endsAt: Date): TimeSlot {
    if (!isValidDate(startsAt) || !isValidDate(endsAt)) {
      throw new InvalidTimeSlotError('Start and end dates must be valid dates');
    }

    const durationHours = getDiffHours(startsAt, endsAt);

    if (durationHours < 0.5 || durationHours > 4) {
      throw new InvalidTimeSlotError('Duration must be between 30 minutes and 4 hours');
    }

    return new TimeSlot(new Date(startsAt), new Date(endsAt));
  }

  get startsAt(): Date {
    return new Date(this.startsAtValue);
  }

  get endsAt(): Date {
    return new Date(this.endsAtValue);
  }

  overlaps(other: TimeSlot): boolean {
    return this.startsAt < other.endsAt && other.startsAt < this.endsAt;
  }
}

Los intervalos que se tocan en sus extremos están permitidos: 10:00–11:00 y 11:00–12:00 no se solapan. Las comparaciones estrictas expresan ese límite de forma explícita.

La comprobación de si un intervalo comienza en el pasado pertenece a Visit.schedule, que recibe now. Un intervalo puede ser válido por sí mismo aunque no sea adecuado para una cita nueva. Separar esos conceptos facilita comprender cada regla.

5.4 Usa un servicio de dominio para reglas entre objetos

La disponibilidad depende de un técnico, un intervalo solicitado y las visitas existentes. TechnicianAvailability recibe esos objetos y rechaza técnicos inactivos o visitas programadas que se solapen.

No consulta registros. La aplicación proporciona la información y el servicio de dominio la evalúa. Las visitas canceladas no bloquean el intervalo y las visitas de otros técnicos no provocan conflictos.

Esta distinción resulta útil al nombrar servicios: el servicio de dominio toma una decisión de negocio, mientras el caso de uso de aplicación coordina los datos y pasos necesarios para llegar a esa decisión.

Los fallos de dominio utilizan errores tipados que derivan de DomainError. Expresan conceptos como PendingRequiredTasksError y TechnicianUnavailableError sin elegir su representación HTTP.

6. Deja que los casos de uso coordinen el trabajo

6.1 Define la capacidad que necesita la aplicación

El puerto del repositorio de órdenes expone tres operaciones:

import type { ServiceOrder } from '../../domain/model/service-order';

export const SERVICE_ORDER_REPOSITORY = Symbol('SERVICE_ORDER_REPOSITORY');

export interface ServiceOrderRepository {
  findById(id: string): Promise<ServiceOrder | null>;
  insert(order: ServiceOrder): Promise<void>;
  save(order: ServiceOrder): Promise<void>;
}

El contrato habla en términos de objetos de dominio. No expone argumentos de Prisma, transacciones SQL ni respuestas HTTP. Separar la inserción del guardado también permite que el adaptador distinga entre un agregado nuevo y uno existente.

El caso de uso de finalización es pequeño por ese mismo motivo. Aquí se omiten los imports:

export class FinalizeServiceOrderUseCase extends ServiceOrderUseCaseBase {
  constructor(repository: ServiceOrderRepository) {
    super(repository);
  }

  async execute(orderId: string): Promise<void> {
    const order = await this.loadOrThrow(orderId);
    order.finalize();
    await this.repository.save(order);
  }
}

La clase base solamente carga la orden y lanza ServiceOrderNotFoundError cuando corresponde. El caso de uso es dueño de la secuencia; el agregado, de las reglas de finalización; el repositorio, de la persistencia.

No hace falta un decorador de Nest. Una prueba unitaria puede construir esta clase directamente con un doble de repositorio.

6.2 Un ejemplo con más pasos: programar una visita

ScheduleVisitUseCase depende de cuatro colaboradores:

// Fragmento del constructor de ScheduleVisitUseCase.
constructor(
  private readonly technicians: TechnicianRepository,
  private readonly visits: VisitRepository,
  private readonly serviceOrders: ServiceOrderLookup,
  private readonly availability: TechnicianAvailability,
) {}

Su comando contiene serviceOrderId, technicianId, startsAt, endsAt y now, con fechas representadas mediante objetos Date. La conversión desde cadenas HTTP ocurre antes de entrar a esta frontera.

El caso de uso crea el intervalo, carga el técnico y la información de la orden y comprueba que esta se encuentre en CREATED o ASSIGNED. Si la orden ya tiene un técnico asignado, debe coincidir con el solicitado. También rechaza una visita ya programada para esa orden.

Después carga las visitas programadas del técnico, pide al servicio de disponibilidad que las evalúe, construye Visit y la inserta. Programar una visita no asigna automáticamente un técnico a la orden de servicio; son operaciones separadas en el modelo actual.

La distribución es práctica: las reglas que utilizan la información de la orden disponible para programación permanecen en la aplicación; las del intervalo, en TimeSlot; las del ciclo de vida de la cita, en Visit; y las de disponibilidad, en el servicio de dominio.

Recibir now permite probar la programación de forma determinista. Actualmente, el adaptador HTTP proporciona new Date(). Otras operaciones de órdenes todavía usan fechas predeterminadas y el repositorio no contiene una abstracción compartida de reloj.

7. Conecta HTTP y persistencia mediante adaptadores

7.1 HTTP adapta los datos de la solicitud a un comando

La capa HTTP es responsable de los decoradores de rutas, los metadatos de Swagger, los DTOs y la validación de las solicitudes. El ValidationPipe global de Nest utiliza whitelist, forbidNonWhitelisted y transform.

Para programar visitas, el DTO comprueba UUIDs, cadenas de fecha ISO estrictas y zonas horarias explícitas. El controlador convierte esas cadenas en fechas y proporciona la hora actual:

// Método de VisitsController; se omiten imports y constructor.
@Post()
@ApiCreatedResponse({ description: 'Visit scheduled' })
async schedule(@Body() dto: ScheduleVisitDto): Promise<{ id: string }> {
  const id = await this.scheduleVisit.execute({
    serviceOrderId: dto.serviceOrderId,
    technicianId: dto.technicianId,
    startsAt: new Date(dto.startsAt),
    endsAt: new Date(dto.endsAt),
    now: new Date(),
  });
  return { id };
}

Otra traducción útil ocurre al crear una orden: el DTO HTTP recibe requiredTasks como objetos con name, mientras la aplicación recibe un arreglo de cadenas. La estructura del transporte no tiene por qué convertirse en la estructura del dominio.

La validación de frontera y la de dominio protegen a consumidores distintos. Una solicitud inválida debe fallar pronto, mientras que las llamadas directas a la aplicación también deben respetar las invariantes. Una cadena de fecha estructuralmente válida puede describir un intervalo que el negocio rechace.

7.2 Traduce los errores de dominio en la frontera

DomainExceptionFilter captura DomainError y convierte su código a HTTP. Por ejemplo:

Condición de dominio	Estado HTTP
Técnico u orden de servicio inexistente	`404`
Intervalo inválido o tareas obligatorias pendientes	`422`
Técnico no disponible o transición de orden inválida	`409`
Conflicto de concurrencia optimista	`409`

Los errores de DTOs y pipes devuelven 400. Los fallos de dominio producen un cuerpo JSON con statusCode, error y message. Los códigos de dominio sin correspondencia se convierten en 500 y el filtro los registra en el log.

Así, el dominio puede evolucionar sus reglas sin importar HttpException, y un futuro adaptador ajeno a HTTP puede traducir los mismos errores de otra manera.

7.3 La persistencia convierte registros en modelos

PrismaServiceOrderRepository implementa el puerto de aplicación. Su método findById carga la raíz y los registros hijos, convierte los enums de base de datos y valores nulos e invoca ServiceOrder.rehydrate.

Al escribir, guarda una instantánea completa en una transacción: inserta o actualiza la raíz, elimina las filas hijas anteriores e inserta las colecciones actuales. También escribe los eventos de dominio pendientes en el Outbox dentro de esa transacción.

Este enfoque es sencillo para un agregado educativo con colecciones moderadas. El coste de escritura crece con el tamaño de las colecciones porque incluso los elementos sin cambios se reemplazan. Una carga mayor podría justificar registrar los cambios de cada elemento o revisar el límite del agregado.

El esquema de Prisma representa relaciones de persistencia. El modelo de dominio representa comportamiento. Mantener ambos explícitos requiere código de mapeo, pero evita que un registro generado de base de datos sea la única representación del negocio.

8. Usa NestJS como punto de composición

Las interfaces de TypeScript desaparecen durante la ejecución. Por eso Nest necesita un token disponible en JavaScript para identificar cada dependencia de salida. Este proyecto utiliza símbolos y proveedores con fábricas.

El siguiente fragmento pertenece a los proveedores de ServiceOrdersModule:

providers: [
  {
    provide: FinalizeServiceOrderUseCase,
    inject: [SERVICE_ORDER_REPOSITORY],
    useFactory: (repository: ServiceOrderRepository) =>
      new FinalizeServiceOrderUseCase(repository),
  },
  { provide: SERVICE_ORDER_REPOSITORY, useClass: PrismaServiceOrderRepository },
],

El adaptador puede utilizar @Injectable() porque vive en infraestructura. La fábrica crea la clase de aplicación y le proporciona su dependencia. Esa es la conexión entre contratos de compilación y objetos en ejecución, utilizando los proveedores personalizados de Nest.

Los módulos pueden conocer las implementaciones concretas: su responsabilidad es ensamblarlas. La aplicación en sí no selecciona un repositorio ni crea un cliente Prisma.

En las pruebas, el mismo caso de uso puede recibir un adaptador en memoria o un mock. Reemplazar un adaptador sigue sujeto a su contrato y semántica; un almacenamiento remoto introduciría problemas de fallos y consistencia que no se resuelven solamente cambiando la composición.

9. Integra módulos mediante un contrato local

Visitas necesita pocos datos de una orden para decidir si permite programarla. Por eso declara su propio contrato en lugar de importar el agregado completo:

export interface ServiceOrderSchedulingInfo {
  id: string;
  status: 'CREATED' | 'ASSIGNED' | 'IN_PROGRESS' | 'FINALIZED' | 'CLOSED';
  assignedTechnicianId?: string;
}

export interface ServiceOrderLookup {
  findById(id: string): Promise<ServiceOrderSchedulingInfo | null>;
}

export const SERVICE_ORDER_LOOKUP = Symbol('SERVICE_ORDER_LOOKUP');

El ServiceOrderLookupAdapter llama al caso de uso exportado GetServiceOrderUseCase y transforma su resultado al contrato local. Convierte el error de orden inexistente en null y propaga los errores inesperados.

Aplicación de visitas     Infraestructura de visitas   Aplicación de órdenes

ScheduleVisitUseCase
        |
        v
ServiceOrderLookup <----- ServiceOrderLookupAdapter --> GetServiceOrderUseCase
 (contrato local)            (traducción)                 (exportado por módulo)

La dependencia concreta entre módulos se concentra en el adaptador y la composición. El caso de uso de programación conoce el puerto local, mientras VisitsModule importa ServiceOrdersModule para conectar el adaptador.

Esta comunicación es síncrona y ocurre dentro del mismo proceso. El evento de cierre de orden no dirige la programación de visitas en la implementación actual. Llevar la integración a mensajería requeriría nuevas decisiones sobre entrega, información desactualizada y reintentos.

10. Temas avanzados: lecturas, escrituras concurrentes y eventos

10.1 Diseña las lecturas según sus consumidores

Cargar un agregado completo tiene sentido para proteger un cambio de estado. Una página de listado suele necesitar una vista más pequeña. service-orders separa ServiceOrderRepository de ServiceOrderQuery, cuyos métodos devuelven vistas de aplicación.

PrismaServiceOrderQuery transforma los registros directamente en esas vistas, sin rehidratar un agregado. El listado se ordena por createdAt e id, ambos descendentes. El cursor contiene ambos valores para mantener un orden determinista incluso cuando las fechas coinciden.

El adaptador solicita un registro adicional para determinar si existe otro cursor. El caso de uso valida límites entre 1 y 100, con 25 como valor predeterminado, y valida filtros y datos del cursor.

Es una separación pragmática de lectura y escritura dentro de la misma aplicación y base de datos. No hay buses de comandos ni proyecciones de lectura asíncronas. El módulo de visitas utiliza sus repositorios para leer; el ejemplo no obliga a ambos módulos a adoptar abstracciones idénticas.

10.2 Detecta escrituras con versiones desactualizadas

Supongamos que dos solicitudes cargan la versión 3 de una orden. Ambas modifican su objeto local. Sin comprobar la versión, el segundo guardado podría sobrescribir el trabajo de la primera solicitud.

Al actualizar, el repositorio realiza esta comprobación dentro de la transacción. El fragmento omite el resto de la persistencia:

const result = await tx.serviceOrderRecord.updateMany({
  where: { id: order.id, version: expectedVersion },
  data: { ...updateInput, version: { increment: 1 } },
});
if (result.count !== 1) throw new ServiceOrderConcurrencyError(order.id);

Solamente una versión coincidente puede avanzar. Una escritura desactualizada falla antes de reemplazar los elementos hijos o guardar sus eventos. Los objetos nuevos comienzan con versión 0 en memoria y se insertan con versión 1.

Después del commit, acknowledgePersistence incrementa la versión en memoria y elimina únicamente los eventos cuyos identificadores se persistieron. Si falla la persistencia, el objeto conserva su versión anterior y los eventos pendientes. El código no reintenta automáticamente una operación de negocio desactualizada: devuelve un conflicto al consumidor.

El repositorio también convierte errores relevantes de Prisma en un error de concurrencia. Puedes revisar la transacción y el manejo de errores en el adaptador completo.

10.3 Persiste eventos de dominio junto con el estado

Cerrar una orden registra ServiceOrderClosedEvent, cuyo nombre es service-orders.service-order.closed.v1. Su contenido incluye los identificadores de orden y contrato, los minutos trabajados, los materiales y la fecha de cierre.

El repositorio copia los eventos pendientes antes de entrar a la transacción e inserta cada uno en outbox_events:

// Dentro de la misma transacción que persiste el agregado.
for (const event of events) {
  await tx.outboxEventRecord.create({
    data: {
      id: event.eventId,
      eventName: event.eventName,
      aggregateId: event.aggregateId,
      payload: event.toPrimitives(),
      occurredAt: event.occurredAt,
    },
  });
}

La garantía buscada en la base de datos es que el estado de la orden, sus elementos hijos y las filas del Outbox se confirmen o reviertan juntos. Esto evita separar la escritura en base de datos de un intento de publicación que podría perderse entre ambos pasos.

Actualmente no existe un worker publicador, un broker ni consumidores de eventos. publishedAt está en el esquema, pero nada en el repositorio marca los eventos como entregados. Una publicación fiable necesitaría un worker, comportamiento de reintentos e idempotencia en los consumidores. Almacenar eventos en el Outbox por sí solo no ofrece entrega exactamente una vez.

Esto también es diferente de Event Sourcing: el repositorio guarda el estado actual del agregado y eventos seleccionados, en lugar de reconstruir órdenes a partir de un historial de eventos.

10.4 Reconoce dónde terminan las garantías

La programación de visitas consulta disponibilidad y después inserta una visita. Dos solicitudes concurrentes pueden observar el mismo intervalo libre y continuar. El esquema tiene índices para esas consultas, pero ninguna restricción de exclusión o mecanismo equivalente que impida solapamientos o varias visitas programadas para una orden.

La comprobación de versión de las órdenes no protege la programación, la desactivación de técnicos ni las lecturas entre módulos. Esas garantías necesitan un diseño separado con restricciones de base de datos, bloqueos o aislamiento transaccional adecuados. Definir una regla en el dominio y protegerla bajo concurrencia son tareas relacionadas, pero diferentes.

11. Prueba el comportamiento en cada frontera

11.1 Las pruebas de dominio solamente necesitan el modelo

Esta prueba de la suite del agregado demuestra la regla de finalización. Se omiten los imports y la función auxiliar createOrder, que crea una orden con una tarea obligatoria pendiente:

it('cannot finalize while required tasks are pending', () => {
  const order = createOrder();
  order.assignTechnician(randomUUID());
  order.addActivity('Inspection', 30);

  expect(() => order.finalize()).toThrow(PendingRequiredTasksError);
});

No interviene ningún módulo de Nest ni base de datos. Otras pruebas de dominio cubren transiciones del ciclo de vida, integridad de instantáneas, copias de fechas, límites de duración, intervalos adyacentes frente a solapados y reglas de cancelación.

11.2 Las pruebas de aplicación sustituyen los puertos de salida

La suite de finalización utiliza un agregado real y un doble de repositorio. Este es el camino exitoso, sin imports:

it('persists the finalized aggregate', async () => {
  const order = ServiceOrder.create({
    customerId: randomUUID(),
    contractId: randomUUID(),
    serviceAddress: 'Plant 1',
    serviceLevel: ServiceLevel.STANDARD,
  });
  order.assignTechnician(randomUUID());
  order.addActivity('Repair', 60);
  const repository = {
    findById: jest.fn().mockResolvedValue(order),
    insert: jest.fn(),
    save: jest.fn().mockResolvedValue(undefined),
  } satisfies ServiceOrderRepository;
  await new FinalizeServiceOrderUseCase(repository).execute(order.id);
  expect(repository.save).toHaveBeenCalledWith(order);
  expect(order.status).toBe(ServiceOrderStatus.FINALIZED);
});

La prueba de orden inexistente también verifica que no se guarde nada. Así se comprueba la coordinación y se dejan los detalles de persistencia a las pruebas del adaptador.

11.3 Explica qué demuestran las pruebas de integración

La suite actual utiliza Jest, ts-jest y Supertest:

Nivel de prueba	Comportamiento real ejercitado	Dependencia sustituida
Dominio	Invariantes y cambios de estado	Ningún objeto del dominio
Aplicación	Coordinación de la finalización	Repositorio
HTTP de visitas	Rutas Nest, DTOs, filtros y casos de uso reales	Puertos de persistencia y consulta de órdenes
Adaptador entre módulos	Mapeo y traducción de errores	Caso de uso externo
Persistencia y consultas	Contratos de llamadas Prisma y mapeo	Cliente Prisma

Las pruebas HTTP abren un puerto local y necesitan permiso para hacerlo. Las de persistencia verifican llamadas y comportamiento de la aplicación alrededor de las transacciones usando dobles; no demuestran rollback, aislamiento ni carreras reales en PostgreSQL.

Ejecuta las pruebas y la compilación con:

npm test -- --runInBand
npm run build

CI genera el cliente Prisma, ejecuta pruebas y compila con Node.js 22. No levanta PostgreSQL. Un siguiente nivel útil sería probar migraciones, transacciones y solicitudes concurrentes contra una base de datos real y desechable. La cobertura existente aporta valor sin implicar que todos los casos de uso tengan pruebas exhaustivas.

12. Ejecuta el proyecto y recorre una orden

Necesitas Node.js 22 o superior, npm y Docker Compose. El proyecto utiliza NestJS 11 y Prisma 6, con PostgreSQL 16 en Compose. Sigue las versiones del repositorio para reproducir estos ejemplos.

Desde una copia nueva del proyecto:

git clone https://github.com/Carlosgmdev/nest-ddd-hexagonal.git
cd nest-ddd-hexagonal
cp .env.example .env
npm install
docker compose up -d --wait
npm run prisma:generate
npm run db:deploy
npm run start:dev

db:deploy aplica las migraciones incluidas en el repositorio; db:migrate sirve para crear migraciones durante el desarrollo. La conexión predeterminada a la base de datos y el puerto están en .env.example.

Swagger está disponible en http://localhost:3000/docs. Las rutas utilizan /api, y GET /api/health devuelve un estado estático de la aplicación en lugar de comprobar la conectividad con la base de datos.

Primero, registra un técnico:

curl -X POST http://localhost:3000/api/technicians \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ana Martinez"}'

Crea una orden sin tareas obligatorias para abreviar el recorrido:

curl -X POST http://localhost:3000/api/service-orders \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId":"11111111-1111-4111-8111-111111111111",
    "contractId":"22222222-2222-4222-8222-222222222222",
    "serviceAddress":"Industrial Avenue 1200, Plant 2",
    "serviceLevel":"PREMIUM",
    "requiredTasks":[]
  }'

Ambos endpoints devuelven { "id": "..." }. Los UUIDs de cliente y contrato son ilustrativos: este ejemplo no tiene módulos de clientes o contratos que validen su existencia. Utiliza los identificadores de orden y técnico recibidos en las siguientes solicitudes.

Reemplaza <order-id> y <technician-id> en los siguientes comandos:

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/technician-assignment' \
  -H 'Content-Type: application/json' \
  -d '{"technicianId":"<technician-id>"}'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/activities' \
  -H 'Content-Type: application/json' \
  -d '{"description":"Electrical inspection","workedMinutes":30}'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/finalize'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/close'

curl 'http://localhost:3000/api/service-orders/<order-id>'

Los endpoints de modificación anteriores devuelven 204. La consulta final muestra CLOSED, la actividad y las fechas del ciclo de vida. El cierre también persiste una fila de Outbox que puedes inspeccionar con npm run db:studio.

Para explorar visitas, utiliza otra orden que todavía esté en CREATED o ASSIGNED. Llama a POST /api/visits con su identificador, el del técnico y valores futuros de startsAt/endsAt que incluyan zona horaria. Prueba un intervalo de 15 minutos, citas adyacentes, un solapamiento y la cancelación mediante POST /api/visits/:id/cancel. Swagger documenta las estructuras de las solicitudes.

13. Elige la estructura cuando sus beneficios justifiquen el coste

Este enfoque facilita localizar y probar el comportamiento del negocio. Nest se ocupa del transporte y la composición, Prisma del acceso a datos y el núcleo expresa el trabajo de la empresa. Nuevos puntos de entrada pueden reutilizar las operaciones de aplicación, mientras los adaptadores contienen las traducciones específicas de cada tecnología.

Los costes son reales: más clases, código de mapeo, definiciones de proveedores y contratos que mantener. Una aplicación pequeña con operaciones sencillas sobre datos puede ser más clara con menos abstracciones. La complejidad del negocio, el cambio esperado y las necesidades de pruebas ofrecen mejores motivos para esta estructura que el deseo de dibujar un hexágono.

Las lecciones más útiles del proyecto son concretas: nombra las operaciones en términos del negocio, conserva las reglas con el modelo que las posee, expresa las necesidades externas mediante puertos y conecta las implementaciones en el borde. Prueba esas fronteras y documenta exactamente qué garantías de consistencia ofrece el código actual.

Si amplías el ejemplo, empieza por una regla nueva y síguela a través del comportamiento del dominio, la coordinación de aplicación, los adaptadores y las pruebas. Mejoras como las pruebas con una base de datos real, la protección de concurrencia al programar visitas y un publicador de Outbox deberían resolver una necesidad concreta.

Referencias y lecturas relacionadas

¿Qué regla de tu aplicación necesita actualmente un framework o una base de datos para probarse? Ese puede ser un buen punto para empezar a aplicar estas fronteras.

Implementing DDD and Hexagonal Architecture in NestJS: A Complete Practical Guide

Carlos Martínez — Wed, 21 Oct 2026 04:00:17 +0000

1. When a service starts doing everything

A NestJS application often begins with a controller, a service, and a few Prisma calls. That structure is easy to understand when the business operation is “save these fields.” Then the requirements change.

An order needs a technician before work can be registered. Required tasks must be completed before finalization. A visit must fit the technician's schedule. Closing an order must record a business event together with the updated state.

When all those decisions live in services that also handle HTTP responses and database records, changing one rule means navigating several technical concerns. Testing the rule can require constructing much more of the application than the rule itself needs.

In this guide, we will follow a service-management API built with TypeScript, NestJS, Prisma, and PostgreSQL. We will use Domain-Driven Design (DDD) to express business behavior and Hexagonal Architecture to control dependencies around it.

You should be comfortable with TypeScript classes, interfaces, async functions, and basic NestJS controllers. You do not need previous DDD experience. The goal is to understand where each responsibility belongs and how the pieces fit together.

The complete example is available in nest-ddd-hexagonal on GitHub. The snippets below are selected from that project; excerpts omit unrelated code and imports where indicated. This is an educational implementation with concrete limits, which we will discuss alongside its benefits.

2. Start with the business and its language

Imagine a company that sends technicians to customer sites. A service order captures the work commitment: customer, contract, address, service level, required tasks, performed activities, and materials used. A visit captures a scheduled appointment with a technician.

The project organizes those concerns into two modules:

Module	Main concepts	Responsibilities
`service-orders`	`ServiceOrder`, activities, materials, required tasks	Record work, enforce the order lifecycle, finalize and close orders
`visits`	`Technician`, `Visit`, `TimeSlot`, `TechnicianAvailability`	Register technicians, schedule visits, check availability, cancel appointments

These modules are candidate context boundaries within a modular monolith. They run in the same process and share PostgreSQL, while maintaining separate models and application contracts. A directory alone does not establish a bounded context; the useful boundary comes from ownership of language, rules, and integration.

Several requirements make this example useful beyond basic CRUD:

Service level determines order priority.
A technician must be assigned before activities or materials can be registered.
Finalization requires at least one activity and no pending required tasks.
Closing requires prior finalization and records a domain event.
Visits last between 30 minutes and four hours and cannot start in the past.
Scheduling checks technician activity, overlapping visits, order status, and assignment.

DDD helps us turn these sentences into named operations. order.finalize() communicates a business decision more directly than assigning a status field in an HTTP handler. Those names also give tests a useful vocabulary.

3. Dependencies point toward the core

In Alistair Cockburn's original Hexagonal Architecture article, the application can be driven and tested independently of its external interfaces. Ports describe interactions with the application; adapters connect those interactions to particular technologies.

This repository implements that idea through three layers:

Layer	Owns	Depends on
Domain	Business concepts, invariants, behavior, domain errors	Its own model and standard runtime APIs
Application	Use cases and contracts for external capabilities	Domain and application ports
Infrastructure	HTTP, DTO validation, persistence, integration adapters	Application, domain, and technical libraries

The core consists of domain and application. In this project, neither imports NestJS or Prisma. It does use standard Node.js APIs such as randomUUID, so framework independence does not imply independence from every runtime.

The following arrows represent source-code dependencies:

HTTP controller ----------> Use case ----------> Domain model
                               |
                               v
                        Application port
                               ^
                               |
Prisma adapter ----------------+
       |
       v
Prisma client / PostgreSQL

Nest module: selects adapters and constructs use cases

At runtime, the use case calls an adapter through the port. The dependency direction remains inward because the use case imports the interface, while the adapter implements that interface.

The repository places outgoing ports in application/ports, where the use cases consume them. Putting ports in the domain can also be reasonable when that layer owns the contract. Hexagonal Architecture does not require one universal folder location.

Incoming operations are exposed through use-case methods. Controllers call them directly; there is no additional interface for every incoming port. The important question is whether the core can execute independently of HTTP and persistence.

4. Organize by capability, then by layer

Here is a shortened view of the project:

src/
├── main.ts
├── app.module.ts
├── shared/
│   ├── domain/
│   └── infrastructure/
└── modules/
    ├── service-orders/
    │   ├── domain/
    │   │   ├── model/
    │   │   ├── events/
    │   │   └── errors/
    │   ├── application/
    │   │   ├── ports/
    │   │   └── use-cases/
    │   ├── infrastructure/
    │   │   ├── http/
    │   │   └── persistence/
    │   └── service-orders.module.ts
    └── visits/
        ├── domain/
        ├── application/
        ├── infrastructure/
        │   ├── http/
        │   ├── persistence/
        │   └── integration/
        └── visits.module.ts

prisma/    # Schema and SQL migrations
test/      # Domain, application, HTTP, and adapter tests

Grouping by business capability keeps related work close together. Within each module, the three layers explain responsibilities. This follows the feature-first organization often associated with vertical slicing, although the repository also retains explicit layers within each module.

The result is easier to navigate than global folders containing every controller, every service, and every entity. It does not make modules automatically independent: visits integrates with service-orders, so extracting one would still require addressing that integration and the shared database.

The shared directory contains small mechanisms such as DomainError, DomainEvent, and AggregateRoot, plus infrastructure support. Business models remain in their owning modules. A shared generic repository would add little value when each module has different persistence needs.

5. Model rules inside the domain

5.1 An aggregate protects a consistency boundary

ServiceOrder is the aggregate root for the order and its child collections. Code changes the order through operations such as assignTechnician, addActivity, completeRequiredTask, finalize, and close.

An aggregate defines a boundary within which related state and rules are managed together. In this implementation, the repository persists the root, activities, materials, and required tasks as one transactional snapshot.

The main lifecycle is:

CREATED -> ASSIGNED -> IN_PROGRESS -> FINALIZED -> CLOSED
             ^              |
             |              +-- activities or materials start work
             +-- technician assignment can be changed before work starts

Finalization additionally requires:
  assigned technician + at least one activity + all required tasks completed

The aggregate implementation has a private constructor and separate factories for creation and rehydration. Creation derives priority from service level and starts the order in CREATED. Rehydration reconstructs an existing order and validates snapshot consistency without replaying business operations.

Here is the actual finalize method, shown without the surrounding class:

finalize(now = new Date()): void {
  this.ensureOperationallyMutable();
  this.ensureTechnicianAssigned();

  if (this.activitiesValue.length === 0) throw new ActivityRequiredError();

  const pending = this.requiredTasksValue
    .filter((task) => !task.completedAt)
    .map((task) => task.id);

  if (pending.length > 0) throw new PendingRequiredTasksError(pending);

  if (this.statusValue !== ServiceOrderStatus.IN_PROGRESS) {
    throw new ServiceOrderInvalidStateError(
      `Only an in-progress service order can be finalized; current state is ${this.statusValue}`,
    );
  }

  const latestWork = Math.max(
    this.createdAtValue.getTime(),
    ...this.activitiesValue.map((activity) => activity.performedAt.getTime()),
    ...this.requiredTasksValue.map((task) => task.completedAt?.getTime() ?? 0),
  );

  const finalizedAt = validDate(now, 'finalizedAt', new Date(latestWork));
  this.statusValue = ServiceOrderStatus.FINALIZED;
  this.finalizedAtValue = finalizedAt;
}

The operation validates its prerequisites before changing status. Registering material alone moves an assigned order into progress, but still does not satisfy the activity requirement for finalization. The timestamp must also be consistent with the recorded work.

These rules apply whether a controller, a test, or a future batch adapter invokes the model. They remain meaningful without any knowledge of status codes or database columns.

5.2 Encapsulation requires protecting references

The aggregate is mutable through its methods. Its getters return frozen child snapshots and copied dates, preventing callers from modifying internal collections indirectly.

That detail matters in JavaScript: readonly is a compile-time restriction, and a Date can change even when its containing property cannot be reassigned. Copying dates on input and output protects the aggregate from those reference mutations.

The implementation also validates rehydrated metadata, child identifiers, lifecycle dates, and state consistency. This is a deliberate safety choice with extra validation cost. Persisted data still crosses a boundary and must be converted into a valid model.

5.3 A value object gives time intervals a meaning

Technician and Visit are entities: their identity persists as their state changes. TimeSlot is a value object: it describes an interval through its values, without a separate identifier or lifecycle. Its role is to represent a valid interval and answer questions about it. The complete source includes date-validation and duration helpers; this excerpt contains its main behavior:

export class TimeSlot {
  private constructor(
    private readonly startsAtValue: Date,
    private readonly endsAtValue: Date,
  ) {}

  static create(startsAt: Date, endsAt: Date): TimeSlot {
    if (!isValidDate(startsAt) || !isValidDate(endsAt)) {
      throw new InvalidTimeSlotError('Start and end dates must be valid dates');
    }

    const durationHours = getDiffHours(startsAt, endsAt);

    if (durationHours < 0.5 || durationHours > 4) {
      throw new InvalidTimeSlotError('Duration must be between 30 minutes and 4 hours');
    }

    return new TimeSlot(new Date(startsAt), new Date(endsAt));
  }

  get startsAt(): Date {
    return new Date(this.startsAtValue);
  }

  get endsAt(): Date {
    return new Date(this.endsAtValue);
  }

  overlaps(other: TimeSlot): boolean {
    return this.startsAt < other.endsAt && other.startsAt < this.endsAt;
  }
}

Intervals that touch at their endpoints are allowed: 10:00–11:00 and 11:00–12:00 do not overlap. The strict comparisons encode that boundary explicitly.

Whether an interval starts in the past belongs to Visit.schedule, which receives now. An interval can be valid in isolation even when it is unsuitable for a new appointment. Separating those concepts makes each rule easier to understand.

5.4 Use a domain service for rules across objects

Availability depends on a technician, a requested interval, and existing visits. TechnicianAvailability receives those objects and rejects inactive technicians or overlapping scheduled visits.

It does not fetch records. The application supplies the information, and the domain service evaluates it. Cancelled visits do not block the interval, and visits belonging to other technicians do not cause a conflict.

This is a useful distinction when naming services: the domain service makes a business decision, while the application use case coordinates the data and steps needed to reach that decision.

Domain failures use typed errors derived from DomainError. They express concepts such as PendingRequiredTasksError and TechnicianUnavailableError without choosing their HTTP representation.

6. Let use cases coordinate the work

6.1 Define the capability the application needs

The service-order repository port exposes three operations:

import type { ServiceOrder } from '../../domain/model/service-order';

export const SERVICE_ORDER_REPOSITORY = Symbol('SERVICE_ORDER_REPOSITORY');

export interface ServiceOrderRepository {
  findById(id: string): Promise<ServiceOrder | null>;
  insert(order: ServiceOrder): Promise<void>;
  save(order: ServiceOrder): Promise<void>;
}

The contract speaks in domain objects. It does not expose Prisma arguments, SQL transactions, or HTTP responses. Separating insertion from saving also allows the adapter to distinguish a new aggregate from an existing one.

The finalization use case is correspondingly small. Imports are omitted here:

export class FinalizeServiceOrderUseCase extends ServiceOrderUseCaseBase {
  constructor(repository: ServiceOrderRepository) {
    super(repository);
  }

  async execute(orderId: string): Promise<void> {
    const order = await this.loadOrThrow(orderId);
    order.finalize();
    await this.repository.save(order);
  }
}

The base class only loads the order and raises ServiceOrderNotFoundError when needed. The use case owns the sequence; the aggregate owns finalization rules; the repository owns persistence.

No Nest decorator is needed. A unit test can construct this class directly with a repository double.

6.2 A more involved example: schedule a visit

ScheduleVisitUseCase depends on four collaborators:

// Constructor excerpt from ScheduleVisitUseCase.
constructor(
  private readonly technicians: TechnicianRepository,
  private readonly visits: VisitRepository,
  private readonly serviceOrders: ServiceOrderLookup,
  private readonly availability: TechnicianAvailability,
) {}

Its command contains serviceOrderId, technicianId, startsAt, endsAt, and now, with dates represented as Date objects. HTTP string parsing happens before entering this boundary.

The use case creates the interval, loads the technician and order information, and checks that the order is CREATED or ASSIGNED. If the order already has an assigned technician, that technician must match the request. It also rejects an existing scheduled visit for that order.

Next it loads the technician's scheduled visits, asks the availability service to evaluate them, constructs Visit, and inserts it. Scheduling a visit does not automatically assign a technician to the service order; those are separate operations in the current model.

The split is practical: rules using the order information available to scheduling stay in the application, interval rules stay in TimeSlot, appointment lifecycle rules stay in Visit, and availability rules stay in the domain service.

Passing now makes scheduling deterministic in tests. The HTTP adapter currently supplies new Date(). Other order operations still use default timestamps, and there is no shared clock abstraction in this repository.

7. Connect HTTP and persistence through adapters

7.1 HTTP adapts request data to a command

The HTTP layer owns route decorators, Swagger metadata, DTOs, and request validation. Nest's global ValidationPipe uses whitelist, forbidNonWhitelisted, and transform.

For visit scheduling, DTO validation checks UUIDs, strict ISO date strings, and explicit timezones. The controller converts those strings into dates and supplies the current time:

// Method excerpt from VisitsController; imports and constructor omitted.
@Post()
@ApiCreatedResponse({ description: 'Visit scheduled' })
async schedule(@Body() dto: ScheduleVisitDto): Promise<{ id: string }> {
  const id = await this.scheduleVisit.execute({
    serviceOrderId: dto.serviceOrderId,
    technicianId: dto.technicianId,
    startsAt: new Date(dto.startsAt),
    endsAt: new Date(dto.endsAt),
    now: new Date(),
  });

  return { id };
}

Another useful translation occurs when creating an order: the HTTP DTO accepts requiredTasks as objects with name, while the application receives an array of strings. A transport shape does not have to become the domain's shape.

Boundary validation and domain validation serve different callers. An invalid request should fail early, while direct application calls must still respect business invariants. A structurally valid date string can describe an interval that the business rejects.

7.2 Translate domain errors at the boundary

DomainExceptionFilter catches DomainError and maps its code to HTTP. For example:

Domain condition	HTTP status
Technician or service order not found	`404`
Invalid interval or pending required tasks	`422`
Technician unavailable or invalid order transition	`409`
Optimistic concurrency conflict	`409`

DTO and pipe failures return 400. Domain failures produce a JSON body with statusCode, error, and message. Unmapped domain codes become 500 and are logged by the filter.

The domain can therefore evolve its rules without importing HttpException, and a future non-HTTP adapter can translate the same errors differently.

7.3 Persistence converts records into models

PrismaServiceOrderRepository implements the application port. Its findById loads the root and child records, maps database enums, converts nullable values, and calls ServiceOrder.rehydrate.

For writes, it stores a complete snapshot in a transaction: the root is inserted or updated, previous child rows are deleted, and the current collections are inserted. Pending domain events are written to the Outbox within that transaction as well.

This approach is straightforward for an educational aggregate with moderate collections. Its write cost grows with collection size because even unchanged children are replaced. A larger workload might justify tracking child changes or revisiting the aggregate boundary.

The Prisma schema represents persistence relationships. The domain model represents behavior. Keeping both explicit costs mapping code, but prevents a generated database record from becoming the only representation of the business.

8. Use NestJS as the composition point

TypeScript interfaces disappear at runtime. Nest therefore needs a runtime token to identify each outgoing dependency. This project uses symbols and factory providers.

The following is an excerpt of the providers in ServiceOrdersModule:

providers: [
  {
    provide: FinalizeServiceOrderUseCase,
    inject: [SERVICE_ORDER_REPOSITORY],
    useFactory: (repository: ServiceOrderRepository) =>
      new FinalizeServiceOrderUseCase(repository),
  },
  { provide: SERVICE_ORDER_REPOSITORY, useClass: PrismaServiceOrderRepository },
],

The adapter can use @Injectable() because it lives in infrastructure. The factory creates the plain application class and supplies its dependency. This is the connection between compile-time contracts and runtime objects, using Nest's custom provider facilities.

Modules are allowed to know concrete implementations: assembling those implementations is their job. The application itself does not select a repository or create a Prisma client.

In tests, the same use case can receive an in-memory adapter or a mock. Replacing an adapter remains subject to its contract and semantics; a remote store would introduce failure and consistency concerns that wiring alone cannot solve.

9. Integrate modules through a local contract

Visits needs a small amount of order information to decide whether scheduling is allowed. It declares its own contract rather than importing the complete order aggregate:

export interface ServiceOrderSchedulingInfo {
  id: string;
  status: 'CREATED' | 'ASSIGNED' | 'IN_PROGRESS' | 'FINALIZED' | 'CLOSED';
  assignedTechnicianId?: string;
}

export interface ServiceOrderLookup {
  findById(id: string): Promise<ServiceOrderSchedulingInfo | null>;
}

export const SERVICE_ORDER_LOOKUP = Symbol('SERVICE_ORDER_LOOKUP');

The ServiceOrderLookupAdapter calls the exported GetServiceOrderUseCase and maps its result to that local shape. It translates a missing-order error to null and propagates unexpected errors.

Visits application        Visits infrastructure       Orders application

ScheduleVisitUseCase
        |
        v
ServiceOrderLookup <----- ServiceOrderLookupAdapter --> GetServiceOrderUseCase
 (local contract)            (translation)                (exported by module)

The concrete cross-module dependency is concentrated in the adapter and module composition. The scheduling use case knows the local port, while VisitsModule imports ServiceOrdersModule to wire the adapter.

This is synchronous communication within one process. The order-closed event does not drive visit scheduling in the current implementation. Moving the integration to messaging would require new behavior around delivery, stale information, and retries.

10. Advanced concerns: reads, concurrent writes, and events

10.1 Shape reads around their consumers

Loading a complete aggregate makes sense when enforcing a state change. A list page usually needs a smaller view. service-orders separates ServiceOrderRepository from ServiceOrderQuery, whose methods return application views.

PrismaServiceOrderQuery maps records directly to those views without rehydrating an aggregate. List results are ordered by createdAt and id, both descending. The cursor carries both values so equal timestamps still have a deterministic order.

The adapter fetches one extra record to determine whether a next cursor exists. The use case validates limits between 1 and 100, with a default of 25, and validates filters and cursor data.

This is a pragmatic separation of reads and writes within one application and database. There are no command buses or asynchronous read projections. The visits module uses its repositories for reads; the example does not force both modules into identical abstractions.

10.2 Detect stale aggregate writes

Suppose two requests load order version 3. Both change their local object. Without a version check, the second save could overwrite the first request's work.

On update, the repository performs this check inside its transaction. The excerpt omits the surrounding persistence work:

const result = await tx.serviceOrderRecord.updateMany({
  where: { id: order.id, version: expectedVersion },
  data: { ...updateInput, version: { increment: 1 } },
});

if (result.count !== 1) throw new ServiceOrderConcurrencyError(order.id);

Only a matching version can advance. A stale write fails before replacing children or storing its events. New objects start at version 0 in memory and are inserted at version 1.

After the transaction commits, acknowledgePersistence advances the in-memory version and clears only the persisted event IDs. If persistence fails, the object keeps its previous version and pending events. The code does not automatically retry a stale business operation; the caller receives a conflict.

The repository also maps relevant Prisma errors to a concurrency error. See the complete adapter for its transaction and error handling.

10.3 Persist domain events atomically with state

Closing an order records ServiceOrderClosedEvent, named service-orders.service-order.closed.v1. Its payload includes order and contract IDs, worked minutes, materials, and the closure timestamp.

The repository copies pending events before entering the transaction and inserts each into outbox_events:

// Inside the same transaction that persists the aggregate.
for (const event of events) {
  await tx.outboxEventRecord.create({
    data: {
      id: event.eventId,
      eventName: event.eventName,
      aggregateId: event.aggregateId,
      payload: event.toPrimitives(),
      occurredAt: event.occurredAt,
    },
  });
}

The intended database guarantee is that the order state, children, and Outbox rows commit together or roll back together. This avoids a separate database write followed by a publication attempt that could be lost between the two steps.

There is currently no publisher worker, broker, or event consumer. publishedAt exists in the schema, but nothing in the repository marks events as delivered. Reliable publication would need a worker, retry behavior, and consumer idempotency. Outbox storage alone does not provide exactly-once delivery.

This is also different from Event Sourcing: the repository stores current aggregate state and selected events, rather than rebuilding orders from an event history.

10.4 Know where the guarantees stop

Visit scheduling reads availability and then inserts a visit. Two concurrent requests can both observe a free interval and both proceed. The schema has indexes for these queries, but no exclusion constraint or equivalent mechanism preventing overlaps or duplicate scheduled visits per order.

The service-order version check does not protect scheduling, technician deactivation, or cross-module reads. Those guarantees would need a separate design using appropriate database constraints, locking, or transaction isolation. Defining a rule in the domain and enforcing it under concurrency are related but distinct engineering tasks.

11. Test the behavior at each boundary

11.1 Domain tests require only the model

This test from the aggregate suite demonstrates the finalization rule. Imports and the createOrder fixture are omitted; the fixture creates an order with one pending required task:

it('cannot finalize while required tasks are pending', () => {
  const order = createOrder();
  order.assignTechnician(randomUUID());
  order.addActivity('Inspection', 30);

  expect(() => order.finalize()).toThrow(PendingRequiredTasksError);
});

No Nest module or database is involved. Other domain tests cover lifecycle transitions, snapshot integrity, copied dates, duration boundaries, overlapping versus adjacent intervals, and cancellation rules.

11.2 Application tests substitute outgoing ports

The finalization suite uses a real aggregate and a repository double. This is its successful path, without imports:

it('persists the finalized aggregate', async () => {
  const order = ServiceOrder.create({
    customerId: randomUUID(),
    contractId: randomUUID(),
    serviceAddress: 'Plant 1',
    serviceLevel: ServiceLevel.STANDARD,
  });

  order.assignTechnician(randomUUID());
  order.addActivity('Repair', 60);

  const repository = {
    findById: jest.fn().mockResolvedValue(order),
    insert: jest.fn(),
    save: jest.fn().mockResolvedValue(undefined),
  } satisfies ServiceOrderRepository;

  await new FinalizeServiceOrderUseCase(repository).execute(order.id);
  expect(repository.save).toHaveBeenCalledWith(order);
  expect(order.status).toBe(ServiceOrderStatus.FINALIZED);
});

The missing-order test also verifies that nothing is saved. This checks orchestration while leaving persistence mechanics to adapter tests.

11.3 Be precise about what integration tests prove

The current suite uses Jest, ts-jest, and Supertest:

Test level	Real behavior exercised	Replaced dependency
Domain	Invariants and state changes	None of the domain objects
Application	Finalization coordination	Repository
Visits HTTP	Nest routing, DTOs, filters, real use cases	Persistence and lookup ports
Module integration adapter	Mapping and error translation	External use case
Persistence and queries	Prisma call contracts and mapping	Prisma client

The HTTP tests open a local port and need permission to bind it. The persistence tests verify calls and application behavior around transactions using doubles; they do not demonstrate real PostgreSQL rollback, isolation, or races.

Run the suite and build with:

npm test -- --runInBand
npm run build

CI generates the Prisma client, runs tests, and builds on Node.js 22. It does not start PostgreSQL. A useful next validation layer would exercise migrations, transactions, and concurrent requests against a real disposable database. Existing coverage is useful without implying that every use case has exhaustive tests.

12. Run the project and follow an order

Use Node.js 22 or newer, npm, and Docker Compose. The project uses NestJS 11 and Prisma 6, with PostgreSQL 16 in Compose. Follow the repository's versions when reproducing these examples.

From a fresh checkout:

git clone https://github.com/Carlosgmdev/nest-ddd-hexagonal.git
cd nest-ddd-hexagonal
cp .env.example .env
npm install
docker compose up -d --wait
npm run prisma:generate
npm run db:deploy
npm run start:dev

db:deploy applies committed migrations; db:migrate is for creating migrations during development. The default database connection and port are in .env.example.

Swagger is available at http://localhost:3000/docs. The routes use /api, and GET /api/health returns a static application status rather than checking database connectivity.

First, register a technician:

curl -X POST http://localhost:3000/api/technicians \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ana Martinez"}'

Create an order without required tasks for a shorter walkthrough:

curl -X POST http://localhost:3000/api/service-orders \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId":"11111111-1111-4111-8111-111111111111",
    "contractId":"22222222-2222-4222-8222-222222222222",
    "serviceAddress":"Industrial Avenue 1200, Plant 2",
    "serviceLevel":"PREMIUM",
    "requiredTasks":[]
  }'

Both endpoints return { "id": "..." }. The customer and contract UUIDs are illustrative: this example has no customer or contract module validating their existence. Use the returned order and technician IDs in the next requests.

Replace <order-id> and <technician-id> in the following commands:

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/technician-assignment' \
  -H 'Content-Type: application/json' \
  -d '{"technicianId":"<technician-id>"}'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/activities' \
  -H 'Content-Type: application/json' \
  -d '{"description":"Electrical inspection","workedMinutes":30}'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/finalize'

curl -X POST 'http://localhost:3000/api/service-orders/<order-id>/close'

curl 'http://localhost:3000/api/service-orders/<order-id>'

The mutation endpoints above return 204. The final read shows CLOSED, the activity, and lifecycle timestamps. The closure also persists an Outbox row, which can be inspected with npm run db:studio.

To explore visits, use a new order that is still CREATED or ASSIGNED, then call POST /api/visits with its ID, the technician ID, and future startsAt/endsAt values containing a timezone. Try a 15-minute slot, adjacent appointments, an overlap, and cancellation through POST /api/visits/:id/cancel. Swagger documents the request shapes.

13. Choose the structure when its benefits justify the cost

This approach makes business behavior easier to locate and test. Nest handles transport and composition, Prisma handles database access, and the core expresses the work the company performs. New entry points can reuse application operations, while adapters contain technology-specific translations.

The costs are real: more classes, mapping code, provider definitions, and contracts to maintain. A small application with simple data operations may be clearer with fewer abstractions. Business complexity, expected change, and testing needs provide better reasons for this structure than a desire to draw a hexagon.

The most useful lessons from this project are concrete: name operations in business terms, keep rules with the model that owns them, make external needs explicit through ports, and compose implementations at the edge. Test those boundaries and document exactly which consistency guarantees the current code provides.

If you extend the example, start with one new business rule and follow it through domain behavior, application coordination, adapters, and tests. Improvements such as real database integration tests, scheduling concurrency protection, and an Outbox publisher should each solve a specific observed need.

References and related reading

What rule in your application currently requires a framework or database to test? That can be a useful place to begin applying these boundaries.

Implementing Hexagonal Architecture in React: A Complete Practical Guide

Carlos Martínez — Wed, 11 Feb 2026 20:31:39 +0000

🎯 Introduction

In the world of frontend development, especially with React, it's common to see projects that start with a simple structure but, over time, become difficult to maintain, test, and scale. Business logic gets mixed with UI components, services are directly coupled to APIs, and tests become complex to write.

Sound familiar? If you've experienced these challenges, Hexagonal Architecture (also known as Ports and Adapters Architecture) combined with Vertical Slicing might be the solution you're looking for.

In this article, I'll show you how to implement this powerful architectural combination in React with TypeScript, using a real Todo management project as an example. We won't just talk about theory; we'll see real code, design decisions, and practical advantages that you can apply from day one.

📚 What is Hexagonal Architecture?

Hexagonal Architecture was proposed by Alistair Cockburn in 2005. Its main goal is to decouple business logic from technical implementation details.

Fundamental principles:

Domain is the center: Business logic doesn't depend on anything external
Dependency inversion: Outer layers depend on inner ones, never the reverse
Ports and Adapters: Abstract interfaces (ports) and concrete implementations (adapters)
Testable by design: Business logic can be tested without UI, without database, without APIs

Visual representation:

┌─────────────────────────────────────────────────┐
│            INFRASTRUCTURE LAYER                 │
│  ┌──────────────────────────────────────────┐   │
│  │         APPLICATION LAYER                │   │
│  │  ┌──────────────────────────────────┐    │   │
│  │  │        DOMAIN LAYER              │    │   │
│  │  │  • Entities                      │    │   │
│  │  │  • Business Rules                │    │   │
│  │  │  • Domain Exceptions             │    │   │
│  │  │  • Ports (Interfaces)            │    │   │
│  │  └──────────────────────────────────┘    │   │
│  │  • Use Cases / Services                  │   │
│  │  • Application Logic                     │   │
│  └──────────────────────────────────────────┘   │
│  • Adapters (Repositories, API clients)         │
│  • UI Components (React)                        │
│  • State Management (Zustand)                   │
│  • Frameworks & Libraries                       │
└─────────────────────────────────────────────────┘

🏗️ Project Structure

Our application follows this folder structure:

src/
└── features/
    └── todos/
        ├── domain/                    # 🔵 Domain Layer
        │   ├── entities/
        │   │   └── todo.entity.ts
        │   ├── enums/
        │   │   └── todo-status.enum.ts
        │   ├── exceptions/
        │   │   ├── domain.exception.ts
        │   │   ├── invalid-todo.exception.ts
        │   │   ├── invalid-todo-status-transition.exception.ts
        │   │   └── todo-not-found.exception.ts
        │   └── ports/
        │       └── todo.repository.ts
        │
        ├── application/               # 🟢 Application Layer
        │   └── services/
        │       ├── todo.service.ts
        │       └── dtos/
        │           └── create-todo.dto.ts
        │
        └── infrastructure/            # 🟡 Infrastructure Layer
            ├── adapters/
            │   └── in-memory-todo.repository.ts
            ├── factories/
            │   └── todo-service.factory.ts
            ├── stores/
            │   └── todo.store.ts
            └── ui/
                ├── components/
                │   ├── TodoItem.tsx
                │   ├── TodosList.tsx
                │   └── TodoStatus.tsx
                └── pages/
                    ├── CreateTodoPage.tsx
                    ├── TodoDetailPage.tsx
                    └── TodosPage.tsx

This structure clearly separates responsibilities and facilitates long-term maintenance.

🧩 Vertical Slicing: Organization by Features

Besides Hexagonal Architecture, this project implements Vertical Slicing, an organizational pattern that structures code by complete features instead of technical layers.

What is Vertical Slicing?

Instead of organizing code by technical type (all components together, all services together), we organize it by business capability. Each feature contains everything needed to function independently:

❌ Horizontal (Traditional):          ✅ Vertical (By Feature):

src/                                  src/
├── components/                       └── features/
│   ├── TodoItem.tsx                      ├── todos/
│   ├── UserProfile.tsx                   │   ├── domain/
│   └── ProductCard.tsx                   │   ├── application/
├── services/                             │   └── infrastructure/
│   ├── todoService.ts                    ├── users/
│   ├── userService.ts                    │   ├── domain/
│   └── productService.ts                 │   ├── application/
└── types/                                │   └── infrastructure/
    ├── Todo.ts                           └── products/
    ├── User.ts                               ├── domain/
    └── Product.ts                            ├── application/
                                              └── infrastructure/

Advantages of Vertical Slicing

1. High Cohesion, Low Coupling

Everything related to "Todos" is in one place. You don't have to jump between 10 different folders to understand a functionality.

2. Efficient Parallel Development

Two developers can work on todos and users simultaneously without merge conflicts, since they're in completely separate folders.

3. Easy to Remove or Extract

No longer need the todos feature? Delete the features/todos/ folder and nothing else breaks. Want to turn it into a micro-frontend? Extract it as an independent package.

4. Simplified Onboarding

A new developer can understand the complete feature by navigating a single folder, without needing to know the entire application.

5. Real Scalability

With 50+ features, it's much more manageable to have 50 feature folders than 50 files in each global technical folder.

6. Technical Decisions per Feature

Each feature can have its own implementation decisions. For example:

todos uses in-memory repository
users could use REST API
analytics could use WebSockets

Vertical Slicing + Hexagonal = 💪

The combination of Vertical Slicing (organization by features) with Hexagonal Architecture (organization by layers within each feature) gives you the best of both worlds:

Feature isolation (Vertical)
Separation of concerns (Hexagonal)
Predictable and consistent code

🔵 Layer 1: Domain (The Heart of the System)

The domain contains pure business logic, without external dependencies. It's the most important code and should be as stable as possible.

1.1 Enums: Todo States

// domain/enums/todo-status.enum.ts
export enum TodoStatus {
  PENDING = "PENDING",
  IN_PROGRESS = "IN_PROGRESS",
  COMPLETED = "COMPLETED",
}

⚠️ Design decision: Using enums instead of magic strings prevents errors and makes code more maintainable.

1.2 Entity: Todo

The Todo entity is a behavior-rich class, not just a data container:

// domain/entities/todo.entity.ts
export interface TodoProps {
  id: number;
  title: string;
  description: string;
  status: TodoStatus;
  createdAt: Date;
  updatedAt: Date;
}

export default class Todo {
  private readonly id: number;
  private title: string;
  private description: string;
  private status: TodoStatus;
  private readonly createdAt: Date;
  private updatedAt: Date;

  constructor(props: TodoProps) {
    this.validateProps(props);
    this.id = props.id;
    this.title = props.title;
    this.description = props.description;
    this.status = props.status;
    this.createdAt = props.createdAt;
    this.updatedAt = props.updatedAt;
  }

  private validateProps(props: TodoProps): void {
    if (!props.title.trim()) {
      throw new InvalidTodoException("title cannot be empty.");
    }
    if (!props.description.trim()) {
      throw new InvalidTodoException("description cannot be empty.");
    }
  }

  // ✅ Getters to maintain immutability
  getId(): number { return this.id; }
  getTitle(): string { return this.title; }
  getStatus(): TodoStatus { return this.status; }

  // ✅ Setters with validation
  setTitle(title: string): void {
    if (!title.trim()) {
      throw new InvalidTodoException("title cannot be empty.");
    }
    this.title = title;
    this.touchUpdatedAt();
  }

  // ✅ Business logic: state transitions
  start(): void {
    if (this.status === TodoStatus.IN_PROGRESS) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.IN_PROGRESS
      );
    }
    if (this.status === TodoStatus.COMPLETED) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.IN_PROGRESS
      );
    }
    this.status = TodoStatus.IN_PROGRESS;
    this.touchUpdatedAt();
  }

  complete(): void {
    if (this.status === TodoStatus.PENDING) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.COMPLETED
      );
    }
    if (this.status === TodoStatus.COMPLETED) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.COMPLETED
      );
    }
    this.status = TodoStatus.COMPLETED;
    this.touchUpdatedAt();
  }

  // ✅ Cloning to avoid mutations
  clone(): Todo {
    return new Todo({
      id: this.id,
      title: this.title,
      description: this.description,
      status: this.status,
      createdAt: this.createdAt,
      updatedAt: this.updatedAt,
    });
  }

  private touchUpdatedAt(): void {
    this.updatedAt = new Date();
  }
}

🎨 Advantages of this implementation:

Centralized validation: Business rules are in one place
Immutability: readonly properties and clone() method
Encapsulation: Private fields, controlled access through getters/setters
Safe state transitions: You can't go from PENDING to COMPLETED directly
Self-documenting: The code clearly explains which operations are valid

1.3 Domain Exceptions

Exceptions are typed and descriptive:

// domain/exceptions/domain.exception.ts
export class DomainException extends Error {
  constructor(message: string) {
    super(message);
    this.name = this.constructor.name;
  }
}

// domain/exceptions/invalid-todo-status-transition.exception.ts
export class InvalidTodoStatusTransitionException extends DomainException {
  constructor(from: string, to: string) {
    super(`Cannot transition from "${from}" to "${to}".`);
  }
}

✅ Benefit: Errors are clear and can be specifically handled in upper layers.

1.4 Ports: Interfaces

Ports are contracts defined by the domain but implemented by infrastructure:

// domain/ports/todo.repository.ts
import type Todo from "../entities/todo.entity";

export default interface TodoRepository {
  create(todo: Todo): Promise<void>;
  update(todo: Todo): Promise<void>;
  delete(id: number): Promise<void>;
  list(): Promise<Todo[]>;
  findById(id: number): Promise<Todo | null>;
}

🔑 Key: The domain defines WHAT it needs, not HOW it's implemented. This is dependency inversion in action.

🟢 Layer 2: Application (Use Cases)

The application layer orchestrates domain logic. This is where services that implement use cases live.

2.1 DTOs (Data Transfer Objects)

DTOs define the data structure for communication between layers:

// application/services/dtos/create-todo.dto.ts
export interface CreateTodoDto {
  title: string;
  description: string;
}

2.2 Application Service

// application/services/todo.service.ts
import Todo from "../../domain/entities/todo.entity";
import { TodoStatus } from "../../domain/enums/todo-status.enum";
import { TodoNotFoundException } from "../../domain/exceptions/todo-not-found.exception";
import type TodoRepository from "../../domain/ports/todo.repository";
import type { CreateTodoDto } from "./dtos/create-todo.dto";

export default class TodoService {
  constructor(private readonly todoRepository: TodoRepository) {}

  async list(): Promise<Todo[]> {
    return this.todoRepository.list();
  }

  async findById(id: number): Promise<Todo | null> {
    return this.todoRepository.findById(id);
  }

  async create(dto: CreateTodoDto): Promise<Todo> {
    const now: Date = new Date();
    const todo: Todo = new Todo({
      id: now.getTime(),
      title: dto.title,
      description: dto.description,
      status: TodoStatus.PENDING,
      createdAt: now,
      updatedAt: now,
    });

    await this.todoRepository.create(todo);
    return todo;
  }

  async delete(id: number): Promise<void> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    await this.todoRepository.delete(id);
  }

  async start(id: number): Promise<Todo> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    const cloned: Todo = todo.clone(); // 🔑 Avoid mutations
    cloned.start();
    await this.todoRepository.update(cloned);
    return cloned;
  }

  async complete(id: number): Promise<Todo> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    const cloned: Todo = todo.clone(); // 🔑 Avoid mutations
    cloned.complete();
    await this.todoRepository.update(cloned);
    return cloned;
  }
}

💡 Important observations:

Dependency injection: Repository is injected through the constructor
Using clones: We never directly mutate the entity obtained from the repository
Existence validations: We throw exceptions if the todo doesn't exist
Thin layer: Only orchestrates, doesn't contain complex business logic

🟡 Layer 3: Infrastructure (Technical Details)

This layer contains concrete implementations of ports and all integration with the outside world.

3.1 Adapter: In-Memory Repository

// infrastructure/adapters/in-memory-todo.repository.ts
import Todo from "../../domain/entities/todo.entity";
import { TodoStatus } from "../../domain/enums/todo-status.enum";
import type TodoRepository from "../../domain/ports/todo.repository";

export default class InMemoryTodoRepository implements TodoRepository {
  private todos: Todo[] = [
    new Todo({
      id: 1,
      title: "Learn TypeScript",
      description: "Study the basics of TypeScript and its features",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    }),
    // ... more example todos
  ];

  async create(todo: Todo): Promise<void> {
    this.todos = [...this.todos, todo];
  }

  async update(updatedTodo: Todo): Promise<void> {
    this.todos = this.todos.map((todo: Todo) =>
      todo.getId() === updatedTodo.getId() ? updatedTodo : todo,
    );
  }

  async delete(id: number): Promise<void> {
    this.todos = this.todos.filter((todo: Todo) => todo.getId() !== id);
  }

  async list(): Promise<Todo[]> {
    return this.todos;
  }

  async findById(id: number): Promise<Todo | null> {
    const todo: Todo | undefined = this.todos.find(
      (todo: Todo) => todo.getId() === id,
    );
    return todo ?? null;
  }
}

🔄 Key advantage: Tomorrow you can create an ApiTodoRepository that makes HTTP calls and only change the factory configuration. Your domain and application won't change a single line.

3.2 Factory Pattern: Dependency Injection

// infrastructure/factories/todo-service.factory.ts
import TodoService from "../../application/services/todo.service";
import type TodoRepository from "../../domain/ports/todo.repository";
import InMemoryTodoRepository from "../adapters/in-memory-todo.repository";

export default class TodoServiceFactory {
  private static instance: TodoService | null = null;

  static getInstance(): TodoService {
    if (!this.instance) {
      const repository: TodoRepository = new InMemoryTodoRepository();
      this.instance = new TodoService(repository);
    }

    return this.instance;
  }
}

💡 Pattern applied: Singleton + Factory to manage service creation and configuration.

3.3 State Management with Zustand

// infrastructure/stores/todo.store.ts
import { create } from "zustand";
import type Todo from "../../domain/entities/todo.entity";
import type { CreateTodoDto } from "../../application/services/dtos/create-todo.dto";
import TodoServiceFactory from "../factories/todo-service.factory";

interface TodoStore {
  todos: Todo[];
  loadingTodos: boolean;
  error: string | null;

  listTodos: () => Promise<void>;
  findTodoById: (id: number) => Promise<Todo | null>;
  createTodo: (dto: CreateTodoDto) => Promise<void>;
  deleteTodo: (id: number) => Promise<void>;
  startTodo: (id: number) => Promise<void>;
  completeTodo: (id: number) => Promise<void>;
}

const useTodoStore = create<TodoStore>()((set, get) => ({
  todos: [],
  loadingTodos: false,
  error: null,

  listTodos: async () => {
    set({ loadingTodos: true, error: null });

    try {
      const todos: Todo[] = await TodoServiceFactory.getInstance().list();
      set({ todos });
    } catch (error) {
      set({ error: (error as Error).message });
    } finally {
      set({ loadingTodos: false });
    }
  },

  createTodo: async (dto: CreateTodoDto) => {
    const todo: Todo = await TodoServiceFactory.getInstance().create(dto);
    set({ todos: [...get().todos, todo] });
  },

  startTodo: async (id: number) => {
    const updated: Todo = await TodoServiceFactory.getInstance().start(id);
    set({
      todos: get().todos.map((todo: Todo) =>
        todo.getId() === id ? updated : todo,
      ),
    });
  },

  completeTodo: async (id: number) => {
    const updated: Todo = await TodoServiceFactory.getInstance().complete(id);
    set({
      todos: get().todos.map((todo: Todo) =>
        todo.getId() === id ? updated : todo,
      ),
    });
  },

  deleteTodo: async (id: number) => {
    await TodoServiceFactory.getInstance().delete(id);
    set({ todos: get().todos.filter((todo: Todo) => todo.getId() !== id) });
  },
}));

export default useTodoStore;

✅ Zustand acts as an adapter between React and our application. Components don't know the internal architecture, only the store.

3.4 React Components

UI components are dumb and reusable:

// infrastructure/ui/components/TodoItem.tsx
export default function TodoItem({ todo }: TodoItemProps): JSX.Element {
  const { startTodo, completeTodo, deleteTodo } = useTodoStore();

  return (
    <div className="group p-5 rounded-xl bg-white border border-slate-200">
      <div className="flex items-start justify-between gap-3">
        <div className="min-w-0 flex-1">
          <Link
            to={`/todos/${todo.getId()}`}
            className="text-lg font-semibold text-slate-800"
          >
            {todo.getTitle()}
          </Link>
          <p className="text-sm text-slate-500 mt-1">
            {todo.getDescription()}
          </p>
        </div>
        <TodoStatus status={todo.getStatus()} />
      </div>

      <div className="flex items-center gap-2 mt-4">
        {todo.getStatus() === TodoStatus.PENDING && (
          <button onClick={() => startTodo(todo.getId())}>
            Start
          </button>
        )}

        {todo.getStatus() === TodoStatus.IN_PROGRESS && (
          <button onClick={() => completeTodo(todo.getId())}>
            Complete
          </button>
        )}

        <button onClick={() => deleteTodo(todo.getId())}>
          Delete
        </button>
      </div>
    </div>
  );
}

🎯 Components as presenters: They only display data and delegate actions to the store.

🧪 Testing: The Great Benefit

Hexagonal Architecture shines especially in testing. Each layer can be tested in isolation.

Entity Test (Domain)

// tests/domain/todo.entity.test.ts
describe("Todo Entity", () => {
  it("should transition from PENDING to IN_PROGRESS", () => {
    const todo = new Todo({
      id: 1,
      title: "Test",
      description: "Test description",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    });

    todo.start();

    expect(todo.getStatus()).toBe(TodoStatus.IN_PROGRESS);
  });

  it("should throw error when transitioning from PENDING to COMPLETED", () => {
    const todo = createTodo({ status: TodoStatus.PENDING });

    expect(() => todo.complete()).toThrow(
      InvalidTodoStatusTransitionException
    );
  });
});

✅ No mocks, no complex setup: Pure business logic testing.

Service Test (Application)

// tests/application/todo.service.test.ts
describe("TodoService", () => {
  let repository: TodoRepository;
  let service: TodoService;

  beforeEach(() => {
    repository = new InMemoryTodoRepository();
    service = new TodoService(repository);
  });

  it("should create a new todo with PENDING status", async () => {
    await service.create({ 
      title: "New Todo", 
      description: "New description" 
    });

    const todos: Todo[] = await service.list();

    expect(todos.length).toBe(4);
    expect(todos[3].getStatus()).toBe(TodoStatus.PENDING);
  });

  it("should return a cloned instance when starting a todo", async () => {
    const original: Todo | null = await service.findById(1);
    const updated: Todo = await service.start(1);

    expect(updated).not.toBe(original); // Different instances
    expect(updated.getStatus()).toBe(TodoStatus.IN_PROGRESS);
  });
});

✅ Lightweight integration test: We use the real (in-memory) repository without needing complex mocks.

UI Test (Infrastructure)

// tests/ui/todo-item.test.tsx
import { render, screen } from "@testing-library/react";
import { BrowserRouter } from "react-router";
import TodoItem from "../../features/todos/infrastructure/ui/components/TodoItem";

describe("TodoItem", () => {
  it("should render todo with title and description", () => {
    const todo = new Todo({
      id: 1,
      title: "Test Todo",
      description: "Test Description",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    });

    render(
      <BrowserRouter>
        <TodoItem todo={todo} />
      </BrowserRouter>
    );

    expect(screen.getByText("Test Todo")).toBeInTheDocument();
    expect(screen.getByText("Test Description")).toBeInTheDocument();
  });
});

🚀 Advantages of This Architecture

1. Maintainability

Each layer has a clear responsibility
Code is easy to understand and modify
Changes are contained within their layer

2. Superior Testability

Business logic without external dependencies
Fast and reliable tests
You don't need to mount the entire app to test a business rule

3. Implementation Flexibility

Change from in-memory to REST API: Only change the adapter
Migrate from Zustand to Redux: Only affects infrastructure
Replace React with Vue: Domain and application intact

4. Scalability

Adding new features follows the same pattern
Multiple developers can work in parallel
Clear structure for large projects

5. Framework Independence

React is just an implementation detail
Business logic isn't coupled to any framework
You can reuse domain and application in other contexts (mobile, backend, etc.)

6. Improves Collaboration

Natural Domain-Driven Design
Ubiquitous language between business and development
Implicit documentation in the structure

7. Vertical Slicing: Natural Organization

Code organized by business capabilities, not by technical type
Self-contained features that are easy to navigate
Parallel development without conflicts
Decoupled features that can be removed or extracted without breaking anything
Faster and more effective developer onboarding

📊 Comparison: Before vs. After

🔴 Traditional React Architecture

src/
├── components/
│   └── TodoItem.tsx  # 500 lines mixing UI, logic, validations
├── pages/
│   └── TodosPage.tsx # Calls fetch() directly, inline validations
├── utils/
│   └── api.ts        # Loose functions
└── types/
    └── Todo.ts       # Simple interface without behavior

Problems:

❌ Business logic scattered across components
❌ Difficult to test (need to mount React)
❌ Direct coupling to APIs
❌ Duplicated validations
❌ Backend changes require touching many files
❌ Mixed features: to understand "todos" you must review multiple folders
❌ Constant merge conflicts in the same files

🟢 With Hexagonal Architecture

src/features/todos/
├── domain/           # The truth of your business
├── application/      # Use case orchestration
└── infrastructure/   # Replaceable technical details

Benefits:

✅ Centralized and testable logic
✅ Simple and reusable components
✅ Contained technological changes
✅ Consistent validations
✅ Fast and reliable tests
✅ Self-contained features in features/todos/
✅ Parallel development without collisions
✅ Easy to remove or extract complete features

🎯 When to Use Hexagonal Architecture + Vertical Slicing

✅ Ideal for:

Enterprise applications with complex business logic
Projects that will scale over time
Medium to large teams (Vertical Slicing facilitates parallel work)
Applications with multiple integrations (APIs, localStorage, WebSockets)
Projects requiring high test coverage
When business logic must be shared (web, mobile, desktop)
Applications with multiple independent features that can grow over time

⚠️ Consider alternatives if:

It's a quick MVP that will likely be discarded
Very simple application (landing page, static blog)
Very small team with very tight deadlines
Initial overhead is greater than expected benefits

🛠️ Project Technology Stack

React 19: UI components
TypeScript 5.9: Type safety and better DX
Vite 7: Modern and fast build tool
Vitest 4: Testing framework compatible with Vite
React Router 7: Client-side routing
Zustand 5: Minimalist state management
TailwindCSS 4: Utility-first CSS (without classes, pure CSS)

📝 Conclusions

The combination of Hexagonal Architecture + Vertical Slicing in React is not just a passing fad; it's an investment in the long-term sustainability of your application. Although it requires more initial structure, the benefits in maintainability, testability, and flexibility are invaluable.

Key Takeaways:

Domain First: Start by modeling your domain, not the UI
Dependency Inversion: Outer layers depend on inner ones
Ports and Adapters: Define interfaces, implement later
Vertical Slicing: Organize by features, not by technical type
Test, Test, Test: The architecture makes testing natural
Pragmatism: Adapt the architecture to your context, not the other way around

Next Steps:

If you want to dive deeper, consider exploring:

Value Objects to model more complex domain concepts
CQRS (Command Query Responsibility Segregation) to separate reads and writes
Event Sourcing if you need complete auditing
Domain Events for communication between aggregates
Specification Pattern for complex queries

🙏 Acknowledgments

This article and the example project are the result of experience applying Clean Architecture and Domain-Driven Design in real React projects.

Special thanks to:

Alistair Cockburn for conceiving Hexagonal Architecture
Robert C. Martin (Uncle Bob) for popularizing Clean Architecture
Eric Evans for Domain-Driven Design, which perfectly complements this architecture
The React community for creating an incredible ecosystem that allows implementing these patterns
The TypeScript developers for making JavaScript predictable and safe
All developers who share knowledge and help raise the level of the industry
And most importantly, to my beautiful family who are my driving force. Mazikeen, Brian, and Fátima, I love you ❤️

About the Author

Carlos Martinez is a Computer Systems Engineer and Full Stack Web Developer with 3 years of experience in the industry. He has worked implementing clean and scalable architectures in production projects, with a special focus on React and TypeScript.

This project was developed as educational material to demonstrate the practical implementation of Hexagonal Architecture in modern React applications, based on real experience applying these patterns in professional environments. The complete code is available on GitHub under MIT license https://github.com/Carlosgmdev/react-hexagonal.

Questions or Feedback?

If you implemented this architecture in your project or have questions, I'd love to hear about your experience. The best way to learn is by sharing knowledge.

Happy coding! 🚀👨‍💻

📚 References and Additional Resources

Last updated: February 2026

#React #TypeScript #CleanArchitecture #HexagonalArchitecture #VerticalSlicing #SoftwareEngineering #Frontend #DomainDrivenDesign

Implementando Arquitectura Hexagonal en React: Una Guía Práctica Completa

Carlos Martínez — Wed, 11 Feb 2026 20:16:13 +0000

🎯 Introducción

En el mundo del desarrollo frontend, especialmente con React, es común ver proyectos que comienzan con una estructura simple pero que, con el tiempo, se convierten en un código difícil de mantener, testear y escalar. La lógica de negocio se mezcla con componentes de UI, los servicios se acoplan directamente a las APIs, y los tests se vuelven complejos de escribir.

¿Te suena familiar? Si has experimentado estos desafíos, la Arquitectura Hexagonal (también conocida como Arquitectura de Puertos y Adaptadores) combinada con Vertical Slicing puede ser la solución que estás buscando.

En este artículo, te mostraré cómo implementar esta poderosa combinación arquitectónica en React con TypeScript, usando un proyecto real de gestión de tareas (Todos) como ejemplo. No solo hablaremos de teoría, sino que veremos código real, decisiones de diseño y ventajas prácticas que aplicarás desde el día uno.

📚 ¿Qué es la Arquitectura Hexagonal?

La Arquitectura Hexagonal fue propuesta por Alistair Cockburn en 2005. Su objetivo principal es desacoplar la lógica de negocio de los detalles técnicos de implementación.

Principios fundamentales:

El dominio es el centro: La lógica de negocio no depende de nada externo
Inversión de dependencias: Las capas externas dependen de las internas, nunca al revés
Puertos y Adaptadores: Interfaces abstractas (puertos) y implementaciones concretas (adaptadores)
Testeable por diseño: La lógica de negocio se puede probar sin UI, sin base de datos, sin APIs

Representación visual:

┌─────────────────────────────────────────────────┐
│            INFRASTRUCTURE LAYER                 │
│  ┌──────────────────────────────────────────┐   │
│  │         APPLICATION LAYER                │   │
│  │  ┌──────────────────────────────────┐    │   │
│  │  │        DOMAIN LAYER              │    │   │
│  │  │  • Entities                      │    │   │
│  │  │  • Business Rules                │    │   │
│  │  │  • Domain Exceptions             │    │   │
│  │  │  • Ports (Interfaces)            │    │   │
│  │  └──────────────────────────────────┘    │   │
│  │  • Use Cases / Services                  │   │
│  │  • Application Logic                     │   │
│  └──────────────────────────────────────────┘   │
│  • Adapters (Repositories, API clients)         │
│  • UI Components (React)                        │
│  • State Management (Zustand)                   │
│  • Frameworks & Libraries                       │
└─────────────────────────────────────────────────┘

🏗️ Estructura del Proyecto

Nuestra aplicación sigue esta estructura de carpetas:

src/
└── features/
    └── todos/
        ├── domain/                    # 🔵 Capa de Dominio
        │   ├── entities/
        │   │   └── todo.entity.ts
        │   ├── enums/
        │   │   └── todo-status.enum.ts
        │   ├── exceptions/
        │   │   ├── domain.exception.ts
        │   │   ├── invalid-todo.exception.ts
        │   │   ├── invalid-todo-status-transition.exception.ts
        │   │   └── todo-not-found.exception.ts
        │   └── ports/
        │       └── todo.repository.ts
        │
        ├── application/               # 🟢 Capa de Aplicación
        │   └── services/
        │       ├── todo.service.ts
        │       └── dtos/
        │           └── create-todo.dto.ts
        │
        └── infrastructure/            # 🟡 Capa de Infraestructura
            ├── adapters/
            │   └── in-memory-todo.repository.ts
            ├── factories/
            │   └── todo-service.factory.ts
            ├── stores/
            │   └── todo.store.ts
            └── ui/
                ├── components/
                │   ├── TodoItem.tsx
                │   ├── TodosList.tsx
                │   └── TodoStatus.tsx
                └── pages/
                    ├── CreateTodoPage.tsx
                    ├── TodoDetailPage.tsx
                    └── TodosPage.tsx

Esta estructura separa claramente las responsabilidades y facilita el mantenimiento a largo plazo.

� Vertical Slicing: Organización por Features

Además de la Arquitectura Hexagonal, este proyecto implementa Vertical Slicing (Corte Vertical), un patrón de organización que estructura el código por features completas en lugar de por capas técnicas.

¿Qué es Vertical Slicing?

En lugar de organizar el código por tipo técnico (todos los componentes juntos, todos los servicios juntos), lo organizamos por capacidad de negocio. Cada feature contiene todo lo necesario para funcionar de forma independiente:

❌ Horizontal (Tradicional):          ✅ Vertical (Por Feature):

src/                                  src/
├── components/                       └── features/
│   ├── TodoItem.tsx                      ├── todos/
│   ├── UserProfile.tsx                   │   ├── domain/
│   └── ProductCard.tsx                   │   ├── application/
├── services/                             │   └── infrastructure/
│   ├── todoService.ts                    ├── users/
│   ├── userService.ts                    │   ├── domain/
│   └── productService.ts                 │   ├── application/
└── types/                                │   └── infrastructure/
    ├── Todo.ts                           └── products/
    ├── User.ts                               ├── domain/
    └── Product.ts                            ├── application/
                                              └── infrastructure/

Ventajas de Vertical Slicing

1. Alta Cohesión, Bajo Acoplamiento

Todo lo relacionado con "Todos" está en un solo lugar. No tienes que saltar entre 10 carpetas diferentes para entender una funcionalidad.

2. Desarrollo en Paralelo Eficiente

Dos desarrolladores pueden trabajar en todos y users simultáneamente sin colisiones de merge, ya que están en carpetas completamente separadas.

3. Fácil de Eliminar o Extraer

¿Ya no necesitas la feature de todos? Elimina la carpeta features/todos/ y nada más se rompe. ¿Quieres convertirla en un micro-frontend? Extraela como un paquete independiente.

4. Onboarding Simplificado

Un nuevo desarrollador puede entender la feature completa navegando una sola carpeta, sin necesidad de conocer toda la aplicación.

5. Escalabilidad Real

Con 50+ features, es mucho más manejable tener 50 carpetas de features que 50 archivos en cada carpeta técnica global.

6. Decisiones Técnicas por Feature

Cada feature puede tener sus propias decisiones de implementación. Por ejemplo:

todos usa repositorio en memoria
users podría usar API REST
analytics podría usar WebSockets

Vertical Slicing + Hexagonal = 💪

La combinación de Vertical Slicing (organización por features) con Arquitectura Hexagonal (organización por capas dentro de cada feature) te da lo mejor de ambos mundos:

Aislamiento de features (Vertical)
Separación de responsabilidades (Hexagonal)
Código predecible y consistente

�🔵 Capa 1: Dominio (El Corazón del Sistema)

El dominio contiene la lógica de negocio pura, sin dependencias externas. Es el código más importante y debe ser lo más estable posible.

1.1 Enums: Estados del Todo

// domain/enums/todo-status.enum.ts
export enum TodoStatus {
  PENDING = "PENDING",
  IN_PROGRESS = "IN_PROGRESS",
  COMPLETED = "COMPLETED",
}

⚠️ Decisión de diseño: Usar enums en lugar de strings mágicos previene errores y hace el código más mantenible.

1.2 Entidad: Todo

La entidad Todo es una clase rica en comportamiento, no solo un contenedor de datos:

// domain/entities/todo.entity.ts
export interface TodoProps {
  id: number;
  title: string;
  description: string;
  status: TodoStatus;
  createdAt: Date;
  updatedAt: Date;
}

export default class Todo {
  private readonly id: number;
  private title: string;
  private description: string;
  private status: TodoStatus;
  private readonly createdAt: Date;
  private updatedAt: Date;

  constructor(props: TodoProps) {
    this.validateProps(props);
    this.id = props.id;
    this.title = props.title;
    this.description = props.description;
    this.status = props.status;
    this.createdAt = props.createdAt;
    this.updatedAt = props.updatedAt;
  }

  private validateProps(props: TodoProps): void {
    if (!props.title.trim()) {
      throw new InvalidTodoException("title cannot be empty.");
    }
    if (!props.description.trim()) {
      throw new InvalidTodoException("description cannot be empty.");
    }
  }

  // ✅ Getters para mantener inmutabilidad
  getId(): number { return this.id; }
  getTitle(): string { return this.title; }
  getStatus(): TodoStatus { return this.status; }

  // ✅ Setters con validación
  setTitle(title: string): void {
    if (!title.trim()) {
      throw new InvalidTodoException("title cannot be empty.");
    }
    this.title = title;
    this.touchUpdatedAt();
  }

  // ✅ Lógica de negocio: transiciones de estado
  start(): void {
    if (this.status === TodoStatus.IN_PROGRESS) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.IN_PROGRESS
      );
    }
    if (this.status === TodoStatus.COMPLETED) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.IN_PROGRESS
      );
    }
    this.status = TodoStatus.IN_PROGRESS;
    this.touchUpdatedAt();
  }

  complete(): void {
    if (this.status === TodoStatus.PENDING) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.COMPLETED
      );
    }
    if (this.status === TodoStatus.COMPLETED) {
      throw new InvalidTodoStatusTransitionException(
        this.status, 
        TodoStatus.COMPLETED
      );
    }
    this.status = TodoStatus.COMPLETED;
    this.touchUpdatedAt();
  }

  // ✅ Clonación para evitar mutaciones
  clone(): Todo {
    return new Todo({
      id: this.id,
      title: this.title,
      description: this.description,
      status: this.status,
      createdAt: this.createdAt,
      updatedAt: this.updatedAt,
    });
  }

  private touchUpdatedAt(): void {
    this.updatedAt = new Date();
  }
}

🎨 Ventajas de esta implementación:

Validación centralizada: Las reglas de negocio están en un solo lugar
Inmutabilidad: Propiedades readonly y método clone()
Encapsulación: Los campos son privados, acceso controlado por getters/setters
Transiciones de estado seguras: No puedes pasar de PENDING a COMPLETED directamente
Self-documenting: El código explica claramente qué operaciones son válidas

1.3 Excepciones de Dominio

Las excepciones son tipadas y descriptivas:

// domain/exceptions/domain.exception.ts
export class DomainException extends Error {
  constructor(message: string) {
    super(message);
    this.name = this.constructor.name;
  }
}

// domain/exceptions/invalid-todo-status-transition.exception.ts
export class InvalidTodoStatusTransitionException extends DomainException {
  constructor(from: string, to: string) {
    super(`Cannot transition from "${from}" to "${to}".`);
  }
}

✅ Beneficio: Los errores son claros y pueden manejarse específicamente en capas superiores.

1.4 Puertos: Interfaces

Los puertos son contratos que define el dominio pero que implementa la infraestructura:

// domain/ports/todo.repository.ts
import type Todo from "../entities/todo.entity";

export default interface TodoRepository {
  create(todo: Todo): Promise<void>;
  update(todo: Todo): Promise<void>;
  delete(id: number): Promise<void>;
  list(): Promise<Todo[]>;
  findById(id: number): Promise<Todo | null>;
}

🔑 Clave: El dominio define QUÉ necesita, no CÓMO se implementa. Esto es la inversión de dependencias en acción.

🟢 Capa 2: Aplicación (Casos de Uso)

La capa de aplicación orquesta la lógica de dominio. Aquí viven los servicios que implementan casos de uso.

2.1 DTOs (Data Transfer Objects)

Los DTOs definen la estructura de datos para comunicación entre capas:

// application/services/dtos/create-todo.dto.ts
export interface CreateTodoDto {
  title: string;
  description: string;
}

2.2 Servicio de Aplicación

// application/services/todo.service.ts
import Todo from "../../domain/entities/todo.entity";
import { TodoStatus } from "../../domain/enums/todo-status.enum";
import { TodoNotFoundException } from "../../domain/exceptions/todo-not-found.exception";
import type TodoRepository from "../../domain/ports/todo.repository";
import type { CreateTodoDto } from "./dtos/create-todo.dto";

export default class TodoService {
  constructor(private readonly todoRepository: TodoRepository) {}

  async list(): Promise<Todo[]> {
    return this.todoRepository.list();
  }

  async findById(id: number): Promise<Todo | null> {
    return this.todoRepository.findById(id);
  }

  async create(dto: CreateTodoDto): Promise<Todo> {
    const now: Date = new Date();
    const todo: Todo = new Todo({
      id: now.getTime(),
      title: dto.title,
      description: dto.description,
      status: TodoStatus.PENDING,
      createdAt: now,
      updatedAt: now,
    });

    await this.todoRepository.create(todo);
    return todo;
  }

  async delete(id: number): Promise<void> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    await this.todoRepository.delete(id);
  }

  async start(id: number): Promise<Todo> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    const cloned: Todo = todo.clone(); // 🔑 Evitamos mutaciones
    cloned.start();
    await this.todoRepository.update(cloned);
    return cloned;
  }

  async complete(id: number): Promise<Todo> {
    const todo: Todo | null = await this.todoRepository.findById(id);
    if (!todo) throw new TodoNotFoundException(id);

    const cloned: Todo = todo.clone(); // 🔑 Evitamos mutaciones
    cloned.complete();
    await this.todoRepository.update(cloned);
    return cloned;
  }
}

💡 Observaciones importantes:

Inyección de dependencias: El repositorio se inyecta por el constructor
Uso de clones: Nunca mutamos directamente la entidad obtenida del repositorio
Validaciones de existencia: Lanzamos excepciones si el todo no existe
Capa delgada: Solo orquesta, no contiene lógica de negocio compleja

🟡 Capa 3: Infraestructura (Detalles Técnicos)

Esta capa contiene las implementaciones concretas de los puertos y toda la integración con el mundo exterior.

3.1 Adaptador: Repositorio en Memoria

// infrastructure/adapters/in-memory-todo.repository.ts
import Todo from "../../domain/entities/todo.entity";
import { TodoStatus } from "../../domain/enums/todo-status.enum";
import type TodoRepository from "../../domain/ports/todo.repository";

export default class InMemoryTodoRepository implements TodoRepository {
  private todos: Todo[] = [
    new Todo({
      id: 1,
      title: "Learn TypeScript",
      description: "Study the basics of TypeScript and its features",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    }),
    // ... más todos de ejemplo
  ];

  async create(todo: Todo): Promise<void> {
    this.todos = [...this.todos, todo];
  }

  async update(updatedTodo: Todo): Promise<void> {
    this.todos = this.todos.map((todo: Todo) =>
      todo.getId() === updatedTodo.getId() ? updatedTodo : todo,
    );
  }

  async delete(id: number): Promise<void> {
    this.todos = this.todos.filter((todo: Todo) => todo.getId() !== id);
  }

  async list(): Promise<Todo[]> {
    return this.todos;
  }

  async findById(id: number): Promise<Todo | null> {
    const todo: Todo | undefined = this.todos.find(
      (todo: Todo) => todo.getId() === id,
    );
    return todo ?? null;
  }
}

🔄 Ventaja clave: Mañana puedes crear un ApiTodoRepository que haga llamadas HTTP y solo cambias la configuración de la factory. Tu dominio y aplicación no cambiarán ni una línea.

3.2 Factory Pattern: Inyección de Dependencias

// infrastructure/factories/todo-service.factory.ts
import TodoService from "../../application/services/todo.service";
import type TodoRepository from "../../domain/ports/todo.repository";
import InMemoryTodoRepository from "../adapters/in-memory-todo.repository";

export default class TodoServiceFactory {
  private static instance: TodoService | null = null;

  static getInstance(): TodoService {
    if (!this.instance) {
      const repository: TodoRepository = new InMemoryTodoRepository();
      this.instance = new TodoService(repository);
    }

    return this.instance;
  }
}

💡 Pattern aplicado: Singleton + Factory para gestionar la creación y configuración de servicios.

3.3 State Management con Zustand

// infrastructure/stores/todo.store.ts
import { create } from "zustand";
import type Todo from "../../domain/entities/todo.entity";
import type { CreateTodoDto } from "../../application/services/dtos/create-todo.dto";
import TodoServiceFactory from "../factories/todo-service.factory";

interface TodoStore {
  todos: Todo[];
  loadingTodos: boolean;
  error: string | null;

  listTodos: () => Promise<void>;
  findTodoById: (id: number) => Promise<Todo | null>;
  createTodo: (dto: CreateTodoDto) => Promise<void>;
  deleteTodo: (id: number) => Promise<void>;
  startTodo: (id: number) => Promise<void>;
  completeTodo: (id: number) => Promise<void>;
}

const useTodoStore = create<TodoStore>()((set, get) => ({
  todos: [],
  loadingTodos: false,
  error: null,

  listTodos: async () => {
    set({ loadingTodos: true, error: null });

    try {
      const todos: Todo[] = await TodoServiceFactory.getInstance().list();
      set({ todos });
    } catch (error) {
      set({ error: (error as Error).message });
    } finally {
      set({ loadingTodos: false });
    }
  },

  createTodo: async (dto: CreateTodoDto) => {
    const todo: Todo = await TodoServiceFactory.getInstance().create(dto);
    set({ todos: [...get().todos, todo] });
  },

  startTodo: async (id: number) => {
    const updated: Todo = await TodoServiceFactory.getInstance().start(id);
    set({
      todos: get().todos.map((todo: Todo) =>
        todo.getId() === id ? updated : todo,
      ),
    });
  },

  completeTodo: async (id: number) => {
    const updated: Todo = await TodoServiceFactory.getInstance().complete(id);
    set({
      todos: get().todos.map((todo: Todo) =>
        todo.getId() === id ? updated : todo,
      ),
    });
  },

  deleteTodo: async (id: number) => {
    await TodoServiceFactory.getInstance().delete(id);
    set({ todos: get().todos.filter((todo: Todo) => todo.getId() !== id) });
  },
}));

export default useTodoStore;

✅ Zustand actúa como un adaptador entre React y nuestra aplicación. Los componentes no conocen la arquitectura interna, solo el store.

3.4 Componentes React

Los componentes UI son tontos y reutilizables:

// infrastructure/ui/components/TodoItem.tsx
export default function TodoItem({ todo }: TodoItemProps): JSX.Element {
  const { startTodo, completeTodo, deleteTodo } = useTodoStore();

  return (
    <div className="group p-5 rounded-xl bg-white border border-slate-200">
      <div className="flex items-start justify-between gap-3">
        <div className="min-w-0 flex-1">
          <Link
            to={`/todos/${todo.getId()}`}
            className="text-lg font-semibold text-slate-800"
          >
            {todo.getTitle()}
          </Link>
          <p className="text-sm text-slate-500 mt-1">
            {todo.getDescription()}
          </p>
        </div>
        <TodoStatus status={todo.getStatus()} />
      </div>

      <div className="flex items-center gap-2 mt-4">
        {todo.getStatus() === TodoStatus.PENDING && (
          <button onClick={() => startTodo(todo.getId())}>
            Start
          </button>
        )}

        {todo.getStatus() === TodoStatus.IN_PROGRESS && (
          <button onClick={() => completeTodo(todo.getId())}>
            Complete
          </button>
        )}

        <button onClick={() => deleteTodo(todo.getId())}>
          Delete
        </button>
      </div>
    </div>
  );
}

🎯 Componentes como presentadores: Solo muestran datos y delegan acciones al store.

🧪 Testing: El Gran Beneficio

La Arquitectura Hexagonal brilla especialmente en testing. Cada capa se puede testear de forma aislada.

Test de Entidad (Dominio)

// tests/domain/todo.entity.test.ts
describe("Todo Entity", () => {
  it("should transition from PENDING to IN_PROGRESS", () => {
    const todo = new Todo({
      id: 1,
      title: "Test",
      description: "Test description",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    });

    todo.start();

    expect(todo.getStatus()).toBe(TodoStatus.IN_PROGRESS);
  });

  it("should throw error when transitioning from PENDING to COMPLETED", () => {
    const todo = createTodo({ status: TodoStatus.PENDING });

    expect(() => todo.complete()).toThrow(
      InvalidTodoStatusTransitionException
    );
  });
});

✅ Sin mocks, sin setup complejo: Testing de lógica de negocio pura.

Test de Servicio (Aplicación)

// tests/application/todo.service.test.ts
describe("TodoService", () => {
  let repository: TodoRepository;
  let service: TodoService;

  beforeEach(() => {
    repository = new InMemoryTodoRepository();
    service = new TodoService(repository);
  });

  it("should create a new todo with PENDING status", async () => {
    await service.create({ 
      title: "New Todo", 
      description: "New description" 
    });

    const todos: Todo[] = await service.list();

    expect(todos.length).toBe(4);
    expect(todos[3].getStatus()).toBe(TodoStatus.PENDING);
  });

  it("should return a cloned instance when starting a todo", async () => {
    const original: Todo | null = await service.findById(1);
    const updated: Todo = await service.start(1);

    expect(updated).not.toBe(original); // Diferentes instancias
    expect(updated.getStatus()).toBe(TodoStatus.IN_PROGRESS);
  });
});

✅ Test de integración ligero: Usamos el repositorio real (en memoria) sin necesidad de mocks complejos.

Test de UI (Infraestructura)

// tests/ui/todo-item.test.tsx
import { render, screen } from "@testing-library/react";
import { BrowserRouter } from "react-router";
import TodoItem from "../../features/todos/infrastructure/ui/components/TodoItem";

describe("TodoItem", () => {
  it("should render todo with title and description", () => {
    const todo = new Todo({
      id: 1,
      title: "Test Todo",
      description: "Test Description",
      status: TodoStatus.PENDING,
      createdAt: new Date(),
      updatedAt: new Date(),
    });

    render(
      <BrowserRouter>
        <TodoItem todo={todo} />
      </BrowserRouter>
    );

    expect(screen.getByText("Test Todo")).toBeInTheDocument();
    expect(screen.getByText("Test Description")).toBeInTheDocument();
  });
});

🚀 Ventajas de Esta Arquitectura

1. Mantenibilidad

Cada capa tiene una responsabilidad clara
El código es fácil de entender y modificar
Los cambios están contenidos en su capa

2. Testabilidad Superior

Lógica de negocio sin dependencias externas
Tests rápidos y confiables
No necesitas montar toda la app para testear una regla de negocio

3. Flexibilidad de Implementación

Cambiar de in-memory a API REST: Solo cambia el adaptador
Migrar de Zustand a Redux: Solo afecta a infraestructura
Reemplazar React por Vue: Dominio y aplicación intactos

4. Escalabilidad

Agregar nuevas features sigue el mismo patrón
Múltiples desarrolladores pueden trabajar en paralelo
Estructura clara para proyectos grandes

5. Independencia de Frameworks

React es solo un detalle de implementación
La lógica de negocio no está acoplada a ningún framework
Puedes reutilizar dominio y aplicación en otros contextos (mobile, backend, etc.)

6. Mejora la Colaboración

Domain-Driven Design natural
Lenguaje ubicuo entre negocio y desarrollo
Documentación implícita en la estructura

7. Vertical Slicing: Organización Natural

Código organizado por capacidades de negocio, no por tipo técnico
Features autocontenidas y fáciles de navegar
Desarrollo en paralelo sin conflictos
Features desacopladas que se pueden eliminar o extraer sin romper nada
Onboarding de desarrolladores más rápido y efectivo

📊 Comparación: Antes vs. Después

🔴 Arquitectura Tradicional de React

src/
├── components/
│   └── TodoItem.tsx  # 500 líneas mezclando UI, lógica, validaciones
├── pages/
│   └── TodosPage.tsx # Llama directamente a fetch(), validaciones inline
├── utils/
│   └── api.ts        # Funciones sueltas
└── types/
    └── Todo.ts       # Interface simple sin comportamiento

Problemas:

❌ Lógica de negocio dispersa en componentes
❌ Difícil de testear (necesitas montar React)
❌ Acoplamiento directo a APIs
❌ Validaciones duplicadas
❌ Cambios en backend requieren tocar muchos archivos
❌ Features mezcladas: para entender "todos" debes revisar múltiples carpetas
❌ Conflictos de merge constantes en los mismos archivos

🟢 Con Arquitectura Hexagonal

src/features/todos/
├── domain/           # La verdad de tu negocio
├── application/      # Orquestación de casos de uso
└── infrastructure/   # Detalles técnicos reemplazables

Beneficios:

✅ Lógica centralizada y testeable
✅ Componentes simples y reutilizables
✅ Cambios tecnológicos contenidos
✅ Validaciones consistentes
✅ Tests rápidos y confiables
✅ Features autocontenidas en features/todos/
✅ Desarrollo en paralelo sin colisiones
✅ Fácil de eliminar o extraer features completas

🎯 Cuándo Usar Arquitectura Hexagonal + Vertical Slicing

✅ Ideal para:

Aplicaciones empresariales con lógica de negocio compleja
Proyectos que escalarán con el tiempo
Equipos medianos a grandes (el Vertical Slicing facilita el trabajo en paralelo)
Aplicaciones con múltiples integraciones (APIs, localStorage, WebSockets)
Proyectos que requieren alta cobertura de tests
Cuando la lógica de negocio debe ser compartida (web, mobile, desktop)
Aplicaciones con múltiples features independientes que pueden crecer con el tiempo

⚠️ Considera alternativas si:

Es un MVP rápido que probablemente se descartará
Aplicación muy simple (landing page, blog estático)
Equipo muy pequeño con plazos muy ajustados
El overhead inicial es mayor que los beneficios esperados

🛠️ Stack Tecnológico del Proyecto

React 19: UI components
TypeScript 5.9: Type safety y mejor DX
Vite 7: Build tool moderno y rápido
Vitest 4: Testing framework compatible con Vite
React Router 7: Client-side routing
Zustand 5: State management minimalista
TailwindCSS 4: Utility-first CSS (sin clases, pure CSS)

📝 Conclusiones

La combinación de Arquitectura Hexagonal + Vertical Slicing en React no es solo una moda pasajera; es una inversión en la sostenibilidad a largo plazo de tu aplicación. Aunque requiere más estructura inicial, los beneficios en mantenibilidad, testabilidad y flexibilidad son invaluables.

Key Takeaways:

Domain First: Empieza por modelar tu dominio, no por la UI
Inversión de Dependencias: Las capas externas dependen de las internas
Puertos y Adaptadores: Define interfaces, implementa después
Vertical Slicing: Organiza por features, no por tipo técnico
Test, Test, Test: La arquitectura hace el testing natural
Pragmatismo: Adapta la arquitectura a tu contexto, no al revés

Próximos Pasos:

Si quieres profundizar, considera explorar:

Value Objects para modelar conceptos de dominio más complejos
CQRS (Command Query Responsibility Segregation) para separar lecturas y escrituras
Event Sourcing si necesitas auditoría completa
Domain Events para comunicación entre agregados
Specification Pattern para consultas complejas

🙏 Agradecimientos

Este artículo y el proyecto de ejemplo son el resultado de la experiencia aplicando Clean Architecture y Domain-Driven Design en proyectos reales de React.

Un agradecimiento especial a:

Alistair Cockburn por concebir la Arquitectura Hexagonal
Robert C. Martin (Uncle Bob) por popularizar Clean Architecture
Eric Evans por Domain-Driven Design, que complementa perfectamente esta arquitectura
La comunidad de React por crear un ecosistema increíble que permite implementar estos patrones
Los desarrolladores de TypeScript por hacer que JavaScript sea predecible y seguro
Todos los developers que comparten conocimiento y ayudan a elevar el nivel de la industria
Y el más importante para mi hermosa familia que es mi motor. Mazikeen, Brian y Fátima los amo ❤️

Sobre el Autor

Carlos Martinez es Ingeniero en Sistemas Computacionales y Desarrollador Web Full Stack con 3 años de experiencia en la industria. Ha trabajado implementando arquitecturas limpias y escalables en proyectos de producción, con especial enfoque en React y TypeScript.

Este proyecto fue desarrollado como material educativo para demostrar la implementación práctica de Arquitectura Hexagonal en aplicaciones React modernas, basándose en experiencia real aplicando estos patrones en entornos profesionales. El código completo está disponible en GitHub bajo licencia MIT https://github.com/Carlosgmdev/react-hexagonal.

¿Preguntas o Feedback?

Si implementaste esta arquitectura en tu proyecto o tienes dudas, me encantaría escuchar tu experiencia. La mejor forma de aprender es compartiendo conocimiento.

Happy coding! 🚀👨‍💻

📚 Referencias y Recursos Adicionales

Última actualización: Febrero 2026

#React #TypeScript #CleanArchitecture #HexagonalArchitecture #VerticalSlicing #SoftwareEngineering #Frontend #DomainDrivenDesign