Software Architecture
Explica cómo diseñar módulos con responsabilidades, invariantes, datos y APIs públicas controladas mediante encapsulación y ocultamiento de información.
Un módulo no es solo una carpeta. Es una frontera que concentra una responsabilidad, protege decisiones internas y ofrece una superficie pública controlada.
La modularidad divide un sistema en unidades que pueden comprenderse y cambiarse con relativa independencia. Para que esa división sea real, cada módulo necesita:
La encapsulación controla cómo se accede a una unidad. El ocultamiento de información decide qué detalles deben permanecer internos porque son probables fuentes de cambio.
Sin módulos efectivos, cualquier parte puede conocer y modificar cualquier otra. Eso produce:
Una carpeta llamada inventory no protege nada si otros módulos importan sus clases internas o escriben directamente sus tablas.
módulo
├── lenguaje y reglas internas
├── datos bajo ownership
├── API pública pequeña
└── detalles ocultos
otros módulos
→ colaboran mediante capacidades
→ no dependen de internalsLa frontera correcta no busca esconder por esconder. Busca evitar que decisiones volátiles se conviertan en dependencias globales.
Un módulo reúne elementos que cambian por razones relacionadas.
Ejemplo:
inventory/
├── application/
├── domain/
├── infrastructure/
├── public.ts
└── tests/Esta estructura solo es útil si public.ts representa la superficie permitida y las reglas impiden imports internos desde otros módulos.
Encapsular significa controlar acceso y preservar invariantes.
export interface InventoryModule {
reserve(input: ReserveStock): Promise<ReservationResult>;
release(input: ReleaseReservation): Promise<void>;
}El consumidor conoce capacidades del dominio. No necesita saber:
private dentro de una clase es una forma local de encapsulación. La arquitectura necesita encapsulación a nivel de módulos, datos y despliegue.
Un módulo debería esconder decisiones con alta probabilidad de cambio o alto costo de propagación:
El principio no consiste en crear wrappers para todo. Se ocultan detalles cuando permitir que crucen el límite aumenta acoplamiento.
Una API pública pequeña reduce obligaciones de compatibilidad.
Incorrecto:
export * from "./domain/entities";
export * from "./infrastructure/models";
export * from "./repositories/internal";Esto expone internals y permite que otros módulos construyan flujos alrededor de detalles.
Preferible:
export { reserveStock, releaseReservation } from "./application/public";
export type { ReserveStock, ReservationResult } from "./contracts";La superficie expresa intenciones, no toda la estructura.
Un módulo no debe compartir responsabilidad sobre una regla crítica.
Inventory posee:
- disponibilidad
- reservas
- movimientos
Orders posee:
- estados del pedido
- reglas de confirmación y cancelaciónOrders puede solicitar una reserva, pero no debería modificar directamente inventory.available.
Sin encapsulación:
await db.inventory.update({
where: { productId },
data: { available: { decrement: quantity } },
});Cualquier consumidor puede producir stock negativo o ignorar tenant y reservas.
Con módulo:
const result = await inventory.reserve({
tenantId,
productId,
quantity,
requestId,
});El módulo valida contexto, cantidad, concurrencia e idempotencia.
Orders recibe ConfirmOrder
→ verifica que el pedido sea confirmable
→ solicita Inventory.reserve
→ Inventory protege la invariante
→ devuelve reserva o rechazo de dominio
→ Orders cambia estado
→ se publica OrderConfirmedCada módulo mantiene su modelo. La colaboración ocurre mediante contratos explícitos.
Las capas agrupan por tipo técnico:
controllers/
services/
repositories/Los módulos agrupan por capacidad:
orders/
inventory/
payments/En sistemas medianos o grandes suele ser útil organizar primero por dominio y aplicar capas dentro de cada módulo. Una estructura global por capas hace que un cambio de negocio atraviese carpetas lejanas y favorece servicios genéricos.
Orders → Inventory → OrdersUn ciclo puede indicar:
Posibles correcciones:
No rompas un ciclo creando una carpeta shared sin comprender el dominio.
Una base compartida puede coexistir con módulos si:
La separación física de bases es una táctica más fuerte, pero añade migraciones, consistencia eventual y operación. No es requisito para modularidad lógica.
Un caso de uso puede coordinar capacidades sin absorber ownership. La transacción y consistencia deben definirse explícitamente.
Un dashboard puede necesitar datos de varios módulos. Usa una proyección de lectura o composición; no conviertas reporting en permiso para compartir escritura.
Tipos como Money pueden ser compartidos si su semántica es estable. Customer suele cambiar de significado entre contextos y no debería universalizarse.
Un módulo por entidad crea fragmentación y coordinación. Los límites deben seguir capacidades e invariantes, no tablas.
Una convención sin verificación se erosiona.
Ejemplo conceptual:
regla:
Orders solo puede importar inventory/public
CI:
falla si importa inventory/infrastructureEl límite no existe si internals y datos siguen abiertos.
Aumenta compatibilidad y hace difícil cambiar internals.
El consumidor termina dependiendo del esquema de persistencia.
Elimina lenguaje del dominio y permite consultas/escrituras arbitrarias.
Produce capas de forwarding sin reducir acoplamiento.
Un proyecto pequeño puede usar pocos módulos y contratos directos. La modularidad debe reducir complejidad, no multiplicar archivos por ritual.
private no basta para modularidad arquitectónica?Dirección de dependencias e inversión de control explica cómo conservar estos límites cuando los casos de uso necesitan bases de datos, proveedores y frameworks.