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>/, conrouter.py,service.py,repository.py,schemas.pyymodels.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) yapp/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/entests/unit/ytests/integration/. Los ADR viven endocs/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
modelsenapp/registry.py, o--autogenerateno 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.