Los Architecture Decision Records (ADR) son el registro formal de las decisiones técnicas más importantes del proyecto. ArccNova v2 tiene 21 ADR formales (ADR-001 a ADR-021) producidos por el equipo de backend, más 22 decisiones internas documentadas por el arquitecto durante el análisis funcional de junio de 2026. Los ADR formales viven enDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/DevCarlosRodriguez/Documentacion-Arccnova-2.0/llms.txt
Use this file to discover all available pages before exploring further.
ArccNova.WebApi/docs/adr/; las decisiones internas están en Documentos/analisis/decisiones-internas.md y se trasladarán a ADR individuales antes de iniciar la implementación de cada módulo.
Los ADR son decisiones vivas. Cuando exista contradicción entre un ADR fuente y cualquier otro documento de especificación, el ADR fuente gana y el documento de especificación debe corregirse. Nunca al revés.
Índice de los 21 ADR formales
| ADR | Título | Estado |
|---|---|---|
| ADR-001 | Arquitectura monolito modular | ✅ Aceptado (actualizado 2026-06-10) |
| ADR-002 | Reset total: greenfield sin migración de datos | ✅ Aceptado |
| ADR-003 | Identity propio con JWT HS256 | ✅ Aceptado (actualizado 2026-06-10) |
| ADR-004 | Pagos: Stripe Connect Express | ✅ Aceptado (actualizado 2026-06-10) |
| ADR-005 | Facturación MX: PAC para CFDI 4.0 | ⏸ Pospuesto (2026-06-10) |
| ADR-006 | Impuestos US: Stripe Tax | ⏸ Pospuesto (2026-06-10) |
| ADR-007 | Branch = proyecto inmobiliario | ✅ Aceptado (punto abierto RH, 2026-06-10) |
| ADR-008 | Mediator: Common.Messaging custom | ✅ Aceptado |
| ADR-009 | RH/Nómina dentro del monolito como módulo único Hr | ✅ Aceptado |
| ADR-010 | Tenancy: entidades con ámbito solo-TenantId | ✅ Aceptado |
| ADR-011 | Despliegue: distroless + nginx, front y back separados | ✅ Aceptado |
| ADR-012 | BD productiva: Aurora PostgreSQL Serverless v2 + advisory lock | ✅ Aceptado |
| ADR-013 | Archivos: AWS S3 con presigned URLs (MinIO en dev) | ✅ Aceptado |
| ADR-014 | Render: operativos en front, legales en back (QuestPDF + SHA-256) | ✅ Aceptado |
| ADR-015 | RBAC granular y dinámico en Identity | ✅ Aceptado (actualizado 2026-06-11) |
| ADR-016 | Módulo nuevo: Treasury (tesorería) | ✅ Aceptado |
| ADR-017 | LegalDocs unificado y firma híbrida con Strategy | ✅ Aceptado |
| ADR-018 | Motor de aprobaciones compartido (un nivel) | ✅ Aceptado |
| ADR-019 | Tiempo real con Server-Sent Events | ✅ Aceptado |
| ADR-020 | Motor de fórmulas de nómina con librería de expresiones | ✅ Aceptado (actualizado 2026-06-11) |
| ADR-021 | Festivos: catálogo único con discriminador de ámbito | ✅ Aceptado |
Decisiones internas del arquitecto (22 decisiones)
Estas decisiones fueron tomadas por el arquitecto durante el análisis de los documentos funcionales del cliente (junio de 2026) y se convertirán en ADR formales antes de implementarse. El detalle completo de cada una vive endecisiones-internas.md v4.2.
| # | Decisión | Impacto principal |
|---|---|---|
| 1 | Contenedores Linux distroless (Ubuntu Chiseled) con libicu + tzdata | Despliegue; descarta librerías nativas de Windows |
| 2 | Healthchecks solo por HTTP en /healthz (sin shell en imagen) | Infraestructura; CI/CD |
| 3 | nginx como reverse proxy; dominio único SaaS con subdominios fijos | CORS estricto; sin subdominios dinámicos por tenant |
| 4 | Front y back en imágenes Docker separadas e independientes | Versionado y despliegue independiente |
| 5 | Aurora PostgreSQL Serverless v2 en producción; PG 17 local en dev | Base de datos; escalado automático |
| 6 | Migraciones al arrancar con advisory lock de sesión (pg_advisory_lock) | Seguridad en escalado horizontal del API |
| 7 | Storage S3 en producción, MinIO en dev (mismo SDK sin #if DEBUG) | Paridad dev/prod (Twelve-Factor) |
| 8 | Subidas y descargas con presigned URLs; binarios nunca transitan por la API | Rendimiento; dimensionado de memoria del contenedor |
| 9 | Documentos operativos se renderizan en el front | Reportes, recibos informativos y vistas de consulta |
| 10 | Documentos legales generados solo en el back con QuestPDF + hash SHA-256 | Contratos, pagarés, recibos timbrados; no repudio |
| 11 | CFDI/PAC y Stripe siempre server-side; front solo actúa como disparador | Custodia de llaves .key/.cer del SAT y API keys |
| 12 | RBAC granular y dinámico desde la fase inicial | Identity; guards del WebClient; auditoría permanente |
| 13 | Treasury confirmado como módulo nuevo | Egresos, recibos de ingreso y resumen financiero |
| 14 | Hr como un solo módulo físico con subcarpetas por contexto | ~48 csproj evitados; Clean Architecture por carpetas |
| 15 | Tenancy con entidades solo-TenantId soportadas nativamente en EF Core | Query filters condicionales; visibilidad corporativa |
| 16 | LegalDocs unificado (Sales + RH comparten el motor de documentos) | Integración futura con firma electrónica centralizada |
| 17 | Festivos: catálogo único con discriminador de ámbito (Global/Tenant/Branch) | Core usa festivos por proyecto; nómina los lee por empresa |
| 18 | Motor de aprobaciones compartido (Shared.Approvals) | Collections, Hr.Requests; un solo nivel binario |
| 19 | Tiempo real vía SSE nativo de .NET 10 | Cobros no identificados; confirmación de pagos en línea |
| 20 | Fórmulas de nómina con librería de expresiones (NCalc/Flee) en sandbox | ADR-020; rechaza parser propio por riesgo de mantenimiento |
| 21 | Firma electrónica con modelo híbrido y patrón Strategy | LegalDocs; trazo simple ahora; NOM-151 como estrategia futura |
| 22 | Política de contraseñas: mín. 8 chars, mayúscula + minúscula + especial | Corrige respuesta C06 del cliente (decía “8 dígitos”) |
Páginas detalladas por tema
Monolito Modular
ADR-001 y ADR-002: por qué un monolito modular en lugar de microservicios, y la decisión de reconstruir desde cero sin migración de datos.
Identity y JWT
ADR-003, ADR-015 y ADR-019: proveedor de identidad propio con JWT HS256, RBAC granular y tiempo real con SSE.
Datos y Storage
ADR-011, ADR-012 y ADR-013: Aurora PostgreSQL Serverless v2, presigned URLs de S3, y despliegue distroless con nginx.
Pagos Stripe
ADR-004: Stripe Connect Express como arquitectura de pagos, con soporte para tarjeta, SPEI y OXXO, y retención del 1% de plataforma.