Conceptos Básicos de Arquitectura y Diseño

8 ejemplos para empezar con la Arquitectura y Diseño para backends de Node.js - 6 básicos y 2 intermedios.

Prerrequisitos

Estos ejemplos asumen Node.js 24.18.0, TypeScript 5.6+, y una pequeña API de Express 5 o Fastify 5.

mkdir orders-api && cd orders-api
npm init -y
npm install express@5 zod
npm install -D typescript@5.6 @types/node @types/express tsx
npx tsc --init

Ejemplos Básicos

1. Comienza con un Monolito Modular

Un único desplegable, límites de módulo claros dentro del repositorio.

src/
├── modules/
│   ├── orders/
│   │   ├── domain/
│   │   ├── application/
│   │   └── infrastructure/
│   └── billing/
├── shared/
└── main.ts

Un proceso, una base de datos, un pipeline de CI: el costo operativo más bajo a pequeña escala
Los módulos se comunican a través de servicios de aplicación o eventos de dominio, no mediante acceso directo a tablas de base de datos
Los límites que dibujes ahora se convertirán en uniones de servicio más adelante si la evidencia lo exige

Relacionado: Monolito Modular - package-by-feature dentro de un único desplegable

2. Separa la Lógica de Dominio de HTTP

Las rutas traducen HTTP; el código de dominio permanece agnóstico al framework.

// src/modules/orders/application/create-order.ts
export type CreateOrderInput = { customerId: string; sku: string; qty: number };
 
export function createOrder(input: CreateOrderInput) {
  if (input.qty <= 0) throw new Error("qty must be positive");
  return { id: crypto.randomUUID(), ...input, status: "pending" as const };
}

// src/modules/orders/infrastructure/http/routes.ts
import express from "express";
import { createOrder } from "../../application/create-order";
 
export const ordersRouter = express.Router();
 
ordersRouter.post("/", (req, res) => {
  const order = createOrder(req.body);
  res.status(201).json({ data: order });
});

createOrder no tiene importaciones de Request o Response: las pruebas unitarias se ejecutan sin HTTP
La validación pertenece al límite (Zod) y a las invariantes de dominio
Cambiar Express por Fastify solo afecta la carpeta de infraestructura

Relacionado: Arquitectura Hexagonal en Node - diseño de puertos y adaptadores

3. Define un Puerto para Sistemas Externos

Un puerto es una interfaz de la que depende el dominio; los adaptadores la implementan.

// src/modules/orders/domain/ports/order-repository.ts
export type Order = { id: string; customerId: string; sku: string; qty: number };
 
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// src/modules/orders/infrastructure/postgres-order-repository.ts
import type { Order, OrderRepository } from "../domain/ports/order-repository";
 
export class PostgresOrderRepository implements OrderRepository {
  constructor(private readonly pool: { query: (sql: string, params: unknown[]) => Promise<unknown> }) {}
 
  async save(order: Order): Promise<void> {
    await this.pool.query(
      "INSERT INTO orders (id, customer_id, sku, qty) VALUES ($1,$2,$3,$4)",
      [order.id, order.customerId, order.sku, order.qty]
    );
  }
 
  async findById(id: string): Promise<Order | null> {
    const rows = await this.pool.query("SELECT * FROM orders WHERE id = $1", [id]);
    return (rows as Order[])[0] ?? null;
  }
}

El dominio importa el puerto, nunca Prisma, pg o clientes de Redis
Las pruebas intercambian un adaptador en memoria sin Docker
Un adaptador por tecnología mantiene las rutas de migración claras

4. Organiza por Característica, No por Capa

Agrupa todo lo relacionado con "pedidos" en un solo lugar en lugar de un árbol global de controllers/.

src/modules/orders/
├── domain/
│   ├── order.ts
│   └── ports/
├── application/
│   ├── create-order.ts
│   └── list-orders.ts
└── infrastructure/
    ├── http/routes.ts
    └── postgres-order-repository.ts

Un cambio en la creación de pedidos afecta una carpeta, no cinco directorios de nivel superior
Los ingenieros nuevos encuentran todo el código de pedidos en un solo lugar
ESLint import/no-restricted-paths puede forzar los límites del módulo

Relacionado: Monolito Modular - forzando límites en un solo repositorio

5. Reconoce Cuándo los Microservicios Son Prematuros

Los sistemas distribuidos compran independencia a costa de la red, las operaciones y la consistencia.

Señal	Mantener monolito	Considerar servicios
Tamaño del equipo	1-3 equipos en un producto	4+ equipos pisando el mismo despliegue
Cadencia de despliegue	Lanzamiento compartido semanal o diario	Necesidad de despliegues horarios por dominio
Acoplamiento de datos	Transacciones compartidas entre características	Contextos delimitados claros con raras uniones cruzadas
Madurez de operaciones	Una única rotación de guardia	Equipo de plataforma para malla, trazado, SLOs

"Podríamos escalar" no es evidencia; mide primero la latencia p95 y el tiempo de espera del equipo
Extrae el módulo más activo primero; mantén el resto monolítico
Cada límite de servicio es un problema de transacción distribuida esperando a ocurrir

Relacionado: Microservicios Cuando Valen la Pena - compensaciones de equipo y costos

6. Registra la Decisión en un ADR

Los Registros de Decisiones de Arquitectura sobreviven a las reorganizaciones y la pérdida de memoria.

# ADR-003: Mantener Monolito Modular para 2026
 
## Estado
Aceptado
 
## Contexto
Tres equipos, pico de 40k RPS, Postgres compartido. Sin equipo de plataforma dedicado.
 
## Decisión
Permanecer como un monolito modular. Reevaluar cuando la facturación necesite una cadencia de despliegue independiente.
 
## Consecuencias
+ Entrega de características más rápida, depuración más sencilla
- Los despliegues de facturación esperan a los lanzamientos de pedidos

Un ADR por bifurcación significativa: framework, base de datos, síncrono vs asíncrono
Vincula los ADRs en las plantillas de PR para que los revisores vean el contexto
Sustituye los ADRs antiguos en lugar de eliminarlos

Relacionado: ADR: Monolito vs Servicios - plantilla específica de Node

Ejemplos Intermedios

7. Cablea la Raíz de Composición al Inicio

La raíz de composición es el único lugar que conoce las implementaciones concretas.

// src/main.ts
import express from "express";
import { PostgresOrderRepository } from "./modules/orders/infrastructure/postgres-order-repository";
import { ordersRouter } from "./modules/orders/infrastructure/http/routes";
 
const pool = { query: async () => [] }; // reemplazar con pg.Pool real
const orderRepo = new PostgresOrderRepository(pool);
 
const app = express();
app.use(express.json());
app.use("/orders", ordersRouter);
app.listen(3000);

Las fábricas viven en main.ts o en un composition-root.ts dedicado
Los servicios de aplicación reciben puertos a través de inyección por constructor
Las pruebas de integración construyen una raíz de composición separada con dobles de prueba

8. Audita Antes de Dividir

Ejecuta una lista de verificación estructural antes de extraer un servicio.

// scripts/architecture-audit.ts - busca importaciones entre módulos
import fs from "node:fs";
import path from "node:path";
 
const modulesDir = "src/modules";
for (const mod of fs.readdirSync(modulesDir)) {
  const files = fs.readdirSync(path.join(modulesDir, mod), { recursive: true }) as string[];
  const tsFiles = files.filter((f) => f.endsWith(".ts"));
  console.log(`${mod}: ${tsFiles.length} files`);
}

Cuenta las importaciones entre módulos y los archivos "dios" antes de cualquier límite de red
Si index.ts reexporta todo, corrige primero la modularidad dentro del monolito
La extracción sin uniones limpias crea dos desplegables enredados

Relacionado: Lista de Verificación de Refactorización - auditorías de index.ts "dios" y dispersión de rutas

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, y NestJS 11.

Prerrequisitos

Estos ejemplos asumen Node.js 24.18.0, TypeScript 5.6+, y una pequeña API de Express 5 o Fastify 5.

mkdir orders-api && cd orders-api
npm init -y
npm install express@5 zod
npm install -D typescript@5.6 @types/node @types/express tsx
npx tsc --init

Ejemplos Básicos

1. Comienza con un Monolito Modular

Un único desplegable, límites de módulo claros dentro del repositorio.

src/
├── modules/
│   ├── orders/
│   │   ├── domain/
│   │   ├── application/
│   │   └── infrastructure/
│   └── billing/
├── shared/
└── main.ts

Un proceso, una base de datos, un pipeline de CI: el costo operativo más bajo a pequeña escala
Los módulos se comunican a través de servicios de aplicación o eventos de dominio, no mediante acceso directo a tablas de base de datos
Los límites que dibujes ahora se convertirán en uniones de servicio más adelante si la evidencia lo exige

Relacionado: Monolito Modular - package-by-feature dentro de un único desplegable

2. Separa la Lógica de Dominio de HTTP

Las rutas traducen HTTP; el código de dominio permanece agnóstico al framework.

// src/modules/orders/application/create-order.ts
export type CreateOrderInput = { customerId: string; sku: string; qty: number };
 
export function createOrder(input: CreateOrderInput) {
  if (input.qty <= 0) throw new Error("qty must be positive");
  return { id: crypto.randomUUID(), ...input, status: "pending" as const };
}

// src/modules/orders/infrastructure/http/routes.ts
import express from "express";
import { createOrder } from "../../application/create-order";
 
export const ordersRouter = express.Router();
 
ordersRouter.post("/", (req, res) => {
  const order = createOrder(req.body);
  res.status(201).json({ data: order });
});

createOrder no tiene importaciones de Request o Response: las pruebas unitarias se ejecutan sin HTTP
La validación pertenece al límite (Zod) y a las invariantes de dominio
Cambiar Express por Fastify solo afecta la carpeta de infraestructura

Relacionado: Arquitectura Hexagonal en Node - diseño de puertos y adaptadores

3. Define un Puerto para Sistemas Externos

Un puerto es una interfaz de la que depende el dominio; los adaptadores la implementan.

// src/modules/orders/domain/ports/order-repository.ts
export type Order = { id: string; customerId: string; sku: string; qty: number };
 
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// src/modules/orders/infrastructure/postgres-order-repository.ts
import type { Order, OrderRepository } from "../domain/ports/order-repository";
 
export class PostgresOrderRepository implements OrderRepository {
  constructor(private readonly pool: { query: (sql: string, params: unknown[]) => Promise<unknown> }) {}
 
  async save(order: Order): Promise<void> {
    await this.pool.query(
      "INSERT INTO orders (id, customer_id, sku, qty) VALUES ($1,$2,$3,$4)",
      [order.id, order.customerId, order.sku, order.qty]
    );
  }
 
  async findById(id: string): Promise<Order | null> {
    const rows = await this.pool.query("SELECT * FROM orders WHERE id = $1", [id]);
    return (rows as Order[])[0] ?? null;
  }
}

El dominio importa el puerto, nunca Prisma, pg o clientes de Redis
Las pruebas intercambian un adaptador en memoria sin Docker
Un adaptador por tecnología mantiene las rutas de migración claras

4. Organiza por Característica, No por Capa

Agrupa todo lo relacionado con "pedidos" en un solo lugar en lugar de un árbol global de controllers/.

src/modules/orders/
├── domain/
│   ├── order.ts
│   └── ports/
├── application/
│   ├── create-order.ts
│   └── list-orders.ts
└── infrastructure/
    ├── http/routes.ts
    └── postgres-order-repository.ts

Un cambio en la creación de pedidos afecta una carpeta, no cinco directorios de nivel superior
Los ingenieros nuevos encuentran todo el código de pedidos en un solo lugar
ESLint import/no-restricted-paths puede forzar los límites del módulo

Relacionado: Monolito Modular - forzando límites en un solo repositorio

5. Reconoce Cuándo los Microservicios Son Prematuros

Los sistemas distribuidos compran independencia a costa de la red, las operaciones y la consistencia.

Señal	Mantener monolito	Considerar servicios
Tamaño del equipo	1-3 equipos en un producto	4+ equipos pisando el mismo despliegue
Cadencia de despliegue	Lanzamiento compartido semanal o diario	Necesidad de despliegues horarios por dominio
Acoplamiento de datos	Transacciones compartidas entre características	Contextos delimitados claros con raras uniones cruzadas
Madurez de operaciones	Una única rotación de guardia	Equipo de plataforma para malla, trazado, SLOs

"Podríamos escalar" no es evidencia; mide primero la latencia p95 y el tiempo de espera del equipo
Extrae el módulo más activo primero; mantén el resto monolítico
Cada límite de servicio es un problema de transacción distribuida esperando a ocurrir

Relacionado: Microservicios Cuando Valen la Pena - compensaciones de equipo y costos

6. Registra la Decisión en un ADR

Los Registros de Decisiones de Arquitectura sobreviven a las reorganizaciones y la pérdida de memoria.

# ADR-003: Mantener Monolito Modular para 2026
 
## Estado
Aceptado
 
## Contexto
Tres equipos, pico de 40k RPS, Postgres compartido. Sin equipo de plataforma dedicado.
 
## Decisión
Permanecer como un monolito modular. Reevaluar cuando la facturación necesite una cadencia de despliegue independiente.
 
## Consecuencias
+ Entrega de características más rápida, depuración más sencilla
- Los despliegues de facturación esperan a los lanzamientos de pedidos

Un ADR por bifurcación significativa: framework, base de datos, síncrono vs asíncrono
Vincula los ADRs en las plantillas de PR para que los revisores vean el contexto
Sustituye los ADRs antiguos en lugar de eliminarlos

Relacionado: ADR: Monolito vs Servicios - plantilla específica de Node

Ejemplos Intermedios

7. Cablea la Raíz de Composición al Inicio

La raíz de composición es el único lugar que conoce las implementaciones concretas.

// src/main.ts
import express from "express";
import { PostgresOrderRepository } from "./modules/orders/infrastructure/postgres-order-repository";
import { ordersRouter } from "./modules/orders/infrastructure/http/routes";
 
const pool = { query: async () => [] }; // reemplazar con pg.Pool real
const orderRepo = new PostgresOrderRepository(pool);
 
const app = express();
app.use(express.json());
app.use("/orders", ordersRouter);
app.listen(3000);

Las fábricas viven en main.ts o en un composition-root.ts dedicado
Los servicios de aplicación reciben puertos a través de inyección por constructor
Las pruebas de integración construyen una raíz de composición separada con dobles de prueba

8. Audita Antes de Dividir

Ejecuta una lista de verificación estructural antes de extraer un servicio.

// scripts/architecture-audit.ts - busca importaciones entre módulos
import fs from "node:fs";
import path from "node:path";
 
const modulesDir = "src/modules";
for (const mod of fs.readdirSync(modulesDir)) {
  const files = fs.readdirSync(path.join(modulesDir, mod), { recursive: true }) as string[];
  const tsFiles = files.filter((f) => f.endsWith(".ts"));
  console.log(`${mod}: ${tsFiles.length} files`);
}

Cuenta las importaciones entre módulos y los archivos "dios" antes de cualquier límite de red
Si index.ts reexporta todo, corrige primero la modularidad dentro del monolito
La extracción sin uniones limpias crea dos desplegables enredados

Relacionado: Lista de Verificación de Refactorización - auditorías de index.ts "dios" y dispersión de rutas

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, y NestJS 11.

Conceptos Básicos de Arquitectura y Diseño

Buscar en la documentación

Conceptos Básicos de Arquitectura y Diseño