Estructura de Carpetas (Screaming Architecture)
Nivel intermedio — organizar el código en carpetas que comuniquen el propósito del sistema, no el framework que usa.
El problema
Abres un proyecto nuevo. Ves las carpetas controllers, models, services, utils. ¿Qué hace este sistema? No hay forma de saberlo — podría ser un e-commerce, un sistema médico, o un juego. La estructura te dice que usa MVC, pero nada sobre el negocio.
Screaming Architecture
Organizar por feature/dominio en vez de por capa técnica: en lugar de una carpeta controllers con todos los controladores mezclados, cada módulo de negocio (orders, catalog, payments) tiene su propia carpeta con todo lo que necesita dentro.
| Aspecto | Por capa técnica | Por feature/dominio |
|---|---|---|
| Navega para | Tipo de archivo (controllers) | Funcionalidad (orders) |
| Escala bien para | Proyectos pequeños | Proyectos medianos/grandes |
| Acoplamiento | Alto (todos los controllers juntos) | Bajo (feature es independiente) |
| Localización de cambios | Un cambio toca 4 carpetas | Un cambio toca 1 carpeta |
Estructura híbrida recomendada
Feature/módulo por fuera, Clean Architecture por dentro de cada módulo:
3 reglas de la estructura
Regla 1 — los módulos son independientes: un módulo puede importar el dominio de otro (una interfaz), nunca su infraestructura concreta.
✗ import { StripeGateway } from '../payments/infrastructure/StripeGateway.js'
Regla 2 — cada módulo expone una API pública vía su index.js: exporta use cases y entities, nunca implementaciones de infraestructura.
Regla 3 — shared/ solo contiene código verdaderamente compartido: utilidades genéricas, base classes, infraestructura común — nunca lógica de negocio específica de un módulo.
Cuándo aplicarlo
| Estructura | Cuándo usarla |
|---|---|
| Por capa técnica | Proyecto pequeño (<5 archivos por tipo), un solo desarrollador |
| Por feature simple | Proyecto mediano, features claros, sin Clean Architecture |
| Feature + Clean | Proyecto complejo, múltiples equipos, lógica de negocio rica |
| Monorepo con packages | Microservicios o módulos con despliegue independiente |
Organizar por feature no impide que alguien importe directamente la infraestructura de otro módulo — solo lo hace más visible en el code review. Las 3 reglas son convención, no un límite que el lenguaje imponga por sí solo; sin revisión activa del equipo, la estructura "grita" un propósito que el código real puede estar traicionando.
Practica: migra de MVC a features
Tienes un proyecto con estructura tradicional MVC: carpetas controllers/, models/, services/, repositories/, routes/, utils/, cada una con archivos de Orders, Products, Payments mezclados.
Reorganízalo en estructura por features (orders/, products/, payments/), aplicando las 3 reglas de independencia entre módulos.