0002. Estructura del proyecto de core-svc-identidad: monolito modular por dominio¶
Estado: Propuesto Fecha: 2026-09-24 Autor: Duval Alcivar Módulo(s) afectado(s): app/, alembic/, 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.
Este repositorio es core-svc-identidad, el servicio de identidad y acceso:
centraliza usuarios, empresas, sucursales, permisos y la navegación
(aplicaciones, módulos y menú) de la plataforma.
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). - Los dominios de este servicio son
usuarios/(login, tokens, credenciales, roles —cat_tipos_usuario— y autorización —rel_usuario_accion—),empresas/,sucursales/,navegacion/(aplicaciones, módulos y menú, ADRs 0006 y 0012 dedocs-site) ycatalogos/(catálogos globales comocat_paises,cat_ciudades,cat_tipos_identificacionycat_generos). El dominiopermisos/se eliminó: el ADR 0023 dedocs-siteunificó la autorización enrel_usuario_accion, y el catálogo de roles vive enusuarios/. - El esquema PostgreSQL de este servicio es
identidad. La documentación lo escribecore.identidadsólo para señalar que vive en la base de datos del core (core_sigfa); el nombre literal del esquema —el que va en la migración y enDATABASE_SCHEMAS— esidentidad. - 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 SQLAlchemy),app/core/(configuración, base de datos, seguridad —firma y verificación de JWT, JWKS y hashing con Argon2—, permisos por endpoint, excepciones de negocio y logging) yapp/api/deps.py(dependencias inyectables: la sesión de base de datos por request —get_db()yget_db_empresa()—, el usuario autenticado y la empresa del token). - Aislamiento por empresa con RLS:
get_db_empresafijaapp.current_empresa_ida partir de los claims del token, nunca del cliente (ADR 0012 transversal), conset_config(..., true)y un listener que lo re-aplica en cada transacción (ADR 0046). Los repositorios no escriben el filtro por empresa.get_empresa_actualdeja la empresa del token disponible como valor, pero hoy ninguna ruta la inyecta: la RLS ya filtra la sesión.mae_usuarios,mae_empresasycat_aplicacionesson globales y no llevan RLS. alembic/guardaenv.pyyversions/, con una migración versionada por cambio. La política RLS de una tabla se crea en la misma migración que la crea (ADR 0012 transversal), de modo que cada tabla nueva nace con RLS activado y con rollback posible.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; las referencias adocs-sitese citan como «ADR 000N transversal».
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).
- Por ser el servicio de identidad, la seguridad y el aislamiento por empresa
viven en
app/core/y en el middleware, no en cada dominio: ningún dominio reimplementa la firma/verificación de JWT ni el filtro por empresa. app/core/es transversal a todos los dominios y crece con los componentes técnicos que el servicio necesite.
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.