Saltar a contenido

0002. Estructura del proyecto: monolito modular por dominio

Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): app/, tests/, docs/

Contexto

El servicio agrupa cuatro dominios de negocio: Promotores, Presupuesto, Pedidos y Visitas. El patrón de capas Router → Service → Repository (ADR 0001 transversal) rige dentro de cada servicio, y crm-svc-clientes ya fijó cómo se ordena en disco (su ADR 0002). Sin una regla igual, los cuatro dominios terminarían mezclados.

Decisión

  • Un paquete por dominio en app/domains/<dominio>/, con router.py, service.py, repository.py, schemas.py y models.py.
  • Las responsabilidades son las del ADR 0001 transversal: el router valida y delega; el service aplica las reglas y no escribe SQL; sólo el repository importa SQLAlchemy; nada de HTTP fuera del router.
  • Lo transversal vive fuera de domains/: app/main.py (composición), app/registry.py (metadata para Alembic), app/core/ (configuración, base de datos, seguridad, tenancy, permisos, errores, logs) y app/api/ (rutas que no son de un dominio, como las sondas).
  • Regla dura: un dominio no importa de otro. Lo compartido va a app/shared/; lo que cruza servicios, a eventos.
  • Las pruebas replican el árbol de app/ en tests/unit/ y tests/integration/. Los ADR viven en docs/adr/ con numeración local.

Alternativas descartadas

  • Agrupar por capa técnica (routers/, services/, ...) — dispersa cada dominio en varias carpetas, como el monolito legado.
  • Hexagonal o DDD con puertos — más abstracciones de las que el equipo necesita hoy (ADR 0001 y 0005 transversales).
  • Una estructura propia distinta a clientes — obliga a reaprender dónde está cada cosa al moverse entre servicios.

Consecuencias

  • Todavía no hay dominios: se crean cuando llegue el modelo de datos.
  • Cada dominio nuevo debe agregar el import de su models en app/registry.py, o --autogenerate no ve sus tablas (ADR 0005).
  • Un PR que importe entre dominios o ponga SQL en un service se rechaza.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.