0002. Estructura del proyecto: monolito modular por dominio¶
Estado: Propuesto Fecha: 2026-09-24 Autor: Duval Alcivar Módulo(s) afectado(s): app/, tests/, docs/
Contexto¶
El patrón de capas Router → Service → Repository (ADR 0001 transversal) rige dentro de cada servicio, pero no dice cómo se agrupan los archivos en el disco. El monolito legado los agrupa por capa técnica: un dominio queda disperso en cuatro carpetas y un cambio de negocio obliga a tocar media docena de lugares.
A eso se suma que la plataforma se parte en 14 microservicios (ADR 0003
transversal), y cada servicio puede tener varios dominios. Sin una regla que
impida el acoplamiento entre dominios de un mismo servicio, el monolito se
reproduce dentro de cada servicio. El patrón de carpetas está fijado en
estructura-microservicios.md de docs-site.
Decisión¶
- Un paquete por dominio de negocio en
app/domains/<dominio>/, con cinco archivos:router.py,service.py,repository.py,schemas.pyymodels.py. La organización es por dominio de negocio, no por capa técnica. - Las responsabilidades y sus prohibiciones son las del ADR 0001 transversal: el
router valida y delega, sin lógica de negocio; el service coordina las reglas y
no escribe SQL; sólo el repository importa SQLAlchemy; y nada de HTTP fuera
del router. Los contratos Pydantic viven en
schemas.py, separados del modelo ORM (ADR 0005 transversal). - Lo transversal vive fuera de
domains/:app/main.py(composición de la aplicación),app/registry.py(importa los modelos de todos los dominios para la metadata de Alembic),app/core/(configuración y componentes técnicos) yapp/api/deps.py(dependencias inyectables: la sesión de base de datos y, más adelante, el usuario y sus permisos). app/shared/es sólo para lo que cruza dos o más dominios de este servicio;app/events/es el outbox de publicación y consumo de eventos de otros servicios.- Regla dura: un dominio no importa de otro dominio. Para comunicarse usan
shared/(síncrono, dentro del servicio) oevents/(asíncrono, entre servicios). Si la única forma de resolver algo es el import cruzado, entonces eran un solo dominio. - Las pruebas replican el árbol de
domains/:tests/unit/<dominio>/ytests/integration/<dominio>/. Los ADR del servicio viven endocs/adr/con numeración local.
Alternativas descartadas¶
- Agrupar por capa técnica (
routers/,services/,repositories/) — es el estilo del monolito legado: dispersa cada dominio y hace que un cambio de negocio toque varias carpetas. - Arquitectura hexagonal o DDD con puertos e interfaces — descartada por ahora por los ADR 0001 y 0005 transversales: agrega abstracciones que el equipo no necesita todavía; puede evolucionarse por dominio si uno lo justifica.
- Un paquete plano por servicio — a medida que el servicio crece, sus dominios terminan mezclados y se pierde el límite entre ellos.
- Dejar la organización a criterio de cada servicio — los 14 terminarían distintos y ningún desarrollador podría moverse entre ellos sin reaprender dónde está cada cosa.
Consecuencias¶
- Un cambio de negocio queda contenido en una sola carpeta, y un dominio se puede extraer a otro servicio sin desarmar el resto.
- Cada dominio se testea sin base de datos real, mockeando su repository.
- Costo: exige disciplina de revisión. Un PR que importe entre dominios, ponga lógica de negocio en un router o SQL en un service se rechaza (ADR 0001 y 0005 transversales).
app/core/crece con los componentes técnicos que cada servicio necesite (seguridad, permisos, excepciones, logging); este ADR no fija su contenido interno.
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.