Saltar a contenido

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.py y models.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 de docs-site) y catalogos/ (catálogos globales como cat_paises, cat_ciudades, cat_tipos_identificacion y cat_generos). El dominio permisos/ se eliminó: el ADR 0023 de docs-site unificó la autorización en rel_usuario_accion, y el catálogo de roles vive en usuarios/.
  • El esquema PostgreSQL de este servicio es identidad. La documentación lo escribe core.identidad só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 en DATABASE_SCHEMAS— es identidad.
  • 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) y app/api/deps.py (dependencias inyectables: la sesión de base de datos por request —get_db() y get_db_empresa()—, el usuario autenticado y la empresa del token).
  • Aislamiento por empresa con RLS: get_db_empresa fija app.current_empresa_id a partir de los claims del token, nunca del cliente (ADR 0012 transversal), con set_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_actual deja la empresa del token disponible como valor, pero hoy ninguna ruta la inyecta: la RLS ya filtra la sesión. mae_usuarios, mae_empresas y cat_aplicaciones son globales y no llevan RLS.
  • alembic/ guarda env.py y versions/, 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) o events/ (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>/ y tests/integration/<dominio>/. Los ADR del servicio viven en docs/adr/ con numeración local; las referencias a docs-site se 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.