ArccNova v2 está construido como un monolito modular sobre .NET 10 con Clean Architecture y CQRS. La decisión de monolito no es accidental: permite un ciclo de desarrollo más rápido en las fases iniciales mientras los límites del dominio se estabilizan, sin renunciar a la posibilidad de extraer módulos como servicios independientes en el futuro. La disciplina de fronteras entre módulos se refuerza automáticamente en el pipeline de CI mediante reglas de arquitectura.Documentation 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.
Stack técnico
| Capa | Tecnología | Notas |
|---|---|---|
| Backend | .NET 10, Clean Architecture, CQRS, mediator propio | Un proceso; 15 módulos como proyectos .csproj independientes |
| Frontend | React 19 SPA | Los documentos operativos (reportes, vistas) los genera el front con datos del back |
| Base de datos | PostgreSQL 17 | Producción: Aurora Serverless v2 |
| Archivos | S3 + URLs prefirmadas | MinIO como sustituto local en desarrollo |
| Pagos | Stripe Checkout + Connect Express | Suscripción SaaS con cuenta principal; pagos del cliente final con Connect |
| Tiempo real | SSE (Server-Sent Events) | Cobros no identificados y confirmaciones de pago en línea |
| Documentos legales | QuestPDF + hash SHA-256 | El back genera el PDF, lo hashea y lo almacena en S3 aislado |
| Despliegue | Contenedores distroless Linux + nginx | Sin shell en producción; superficie de ataque mínima |
Monolito modular: la disciplina de fronteras
El monolito modular de ArccNova v2 se despliega como un único proceso, pero cada módulo está organizado internamente con sus propias capas de Clean Architecture:.Contracts de otro módulo. Las referencias directas entre capas de módulos distintos están prohibidas y son detectadas automáticamente por NetArchTest.Rules en el pipeline de CI.
Cada módulo puede ser extraído como un servicio independiente cuando el negocio lo justifique — el límite del monolito se mantiene por disciplina + refuerzo automático en CI.
Infraestructura compartida (chasis)
El chasis es el conjunto de proyectos compartidos que todos los módulos heredan sin escribir código adicional. A fecha de 13 de junio de 2026 el chasis está completamente operativo.Shared.Kernel
BaseEntity con ID tipado, interfaces de ámbito (ITenantScoped, IBranchScoped) y contratos base del dominio. Define el vocabulario común para que los módulos apliquen aislamiento multi-tenant de forma uniforme (ADR-022).Shared.Database
AppDbContext con query filters automáticos de tenant/branch, interceptor de auditoría y soft-delete, advisory lock en migraciones para evitar carreras en despliegues paralelos, seeders y endpoint /healthz.Shared.Web
BaseApiController, envelope de respuesta unificado, atributo [HasPermission] para autorización granular por módulo y acción. El gancho ya está activo; el almacén real de roles se implementa con la extensión RBAC de Identity.Shared.Branch
Resuelve el
tenant_id y el branch_id activos desde los claims del JWT y los expone como servicio de contexto. Todo acceso a datos multi-tenant pasa por aquí.Shared.Approvals
Motor de aprobaciones en esqueleto. Se activa con el módulo Hr para gestionar solicitudes de empleados (vacaciones, permisos, etc.). El núcleo inmobiliario no lo usa en las fases iniciales.
Estado del pipeline HTTP
El host ya tiene activos: autenticación JWT, CORS, rate limiting, versionado de API (/api/v1/) y Swagger. Los ganchos provisionales de permisos (autenticado = autorizado) y cuotas (sin límite) se sustituyen al construir la extensión RBAC de Identity y el módulo BillingSaas respectivamente.
Estado de los módulos (13 de junio de 2026)
Tax, Rentals y Materials no se crearon como proyectos. Tax está pospuesto (ADR-005/ADR-006); Rentals y Materials están en análisis del requisitor (T04).
Fases de construcción
El plan de entrega está dividido en cinco fases incrementales más una fase propia para RH. Cada fase desbloquea capacidades de negocio completas.| Fase | Módulos | Capacidad desbloqueada |
|---|---|---|
| Fase 1 — Foundation | Identity (RBAC), Tenants, Branches, Geo, Files, BillingSaas | Empresa operativa: proyectos, usuarios con roles y permisos, catálogos, archivos. El paywall del plan empieza a aplicar. |
| Fase 2 — Inmobiliario base | Properties, Contacts, LegalDocs | Inventario vendible (manzanas y lotes), directorio de clientes y plantillas de contrato con variables. |
| Fase 3 — Operación comercial | Sales, Financing, Collections, Treasury | Ciclo comercial completo: cotizar, reservar, vender, financiar, cobrar con mora, registrar movimientos de tesorería. |
| Fase 4 — Pagos en línea | Payments | El cliente final paga sus cuotas en línea (tarjeta, SPEI, OXXO) vía Stripe Connect Express. ArccNova retiene el 1 % de cada cobro. |
| Fase 5 — Reportes | Reports | ~20 reportes operativos (ventas, cobranza, corte de caja, etc.) y carta de cobranza. Se construye de forma incremental conforme cada fuente de datos existe. |
| Fase propia — RH | Hr (8 contextos) + Shared.Approvals | Estructura organizacional, expediente, asistencia, horarios, solicitudes, nómina por conceptos y vacaciones. Prerequisitos: Identity RBAC + LegalDocs + catálogo de festivos + resolución de R20. |
Estrategia de renderizado de documentos
ArccNova v2 distingue dos categorías de documentos con estrategias de generación completamente distintas:- Documentos operativos
- Documentos de valor legal
Quién los genera: el frontend (React 19 SPA) con datos que entrega el backend.Ejemplos: reportes de ventas, estado de cuenta del cliente, corte de caja, listas de cobranza, vistas del proyecto.Por qué en el front: son documentos de consulta y presentación; su formato puede variar según el contexto sin impacto legal. Delegar el render al cliente reduce la carga del servidor y permite estilos ricos sin latencia adicional.
Tiempo real con SSE
ArccNova v2 usa Server-Sent Events (SSE) para las notificaciones en tiempo real, descartando SignalR de forma explícita (Decisión 19). Los dos casos de uso que activan SSE son:| Evento | Descripción |
|---|---|
| Cobro no identificado | Un pago entra al sistema vía Stripe Connect pero no puede asociarse automáticamente a una cuota. Se notifica al operador en tiempo real para que lo identifique manualmente. |
| Confirmación de pago en línea | El cliente final completa un pago (tarjeta, SPEI, OXXO). La confirmación del webhook de Stripe llega al backend y se propaga vía SSE al dashboard del asesor/admin sin necesidad de recargar la página. |
Stripe: dos flujos distintos
ArccNova v2 usa Stripe de dos maneras diferentes que no deben confundirse:| Flujo | Propósito | Implementación |
|---|---|---|
| Suscripción SaaS | Cobrar la mensualidad del plan a la empresa cliente | Stripe Checkout + portal de facturación. La cuenta principal de ArccNova recibe los pagos. |
| Pagos del cliente final | Que el comprador de un lote pague sus cuotas | Stripe Connect Express. El dinero cae en la cuenta bancaria de la empresa inmobiliaria. ArccNova retiene automáticamente el 1 % de cada transacción (T03). |
Seguridad y despliegue
Contenedores distroless
La imagen de producción es distroless Linux: sin shell, sin gestor de paquetes, superficie de ataque mínima. El backend corre detrás de nginx que termina TLS y sirve el SPA de React.
Multi-tenancy en base de datos
El aislamiento entre tenants se implementa mediante
query filters automáticos en AppDbContext. Ninguna query llega al ORM sin el filtro de tenant_id activo, eliminando la posibilidad de fuga de datos entre empresas por omisión.Soft-delete y auditoría
El interceptor de
AppDbContext registra automáticamente CreatedAt, UpdatedAt, CreatedBy y UpdatedBy en todas las entidades que implementen las interfaces correspondientes de Shared.Kernel. El borrado lógico (soft-delete) aplica por default.Migraciones seguras
Un advisory lock de PostgreSQL garantiza que solo un proceso aplica migraciones a la vez en despliegues paralelos o rolling updates, evitando condiciones de carrera en la base de datos.