Arquitectura del Sistema — ITECEL ADM

Última actualización: 2026-09-27
Estado: Documento Vivo / Arquitectura
Propósito: Describir la topología de servicios, responsabilidades de capas, superficies de despliegue, la cadena de identidad y sus dependencias técnicas.

---

Índice

1. Stack Tecnológico y Visión General
2. Responsabilidades: Frontend vs Backend
3. Diagrama de Arquitectura General
4. Cadena de Identidad y Resolución de Contextos
5. Hallazgo Crítico: Vínculos por Email vs UUID
6. Referencias a Documentación Complementaria

---

1. Stack Tecnológico y Visión General

ITECEL ADM es una plataforma SaaS multi-condominio diseñada para la administración financiera, contable y operativa de comunidades residenciales y comerciales.

• Frontend: Single Page Application (SPA) construida con React 18 + TypeScript + Vite + Tailwind CSS.
• Hosting Frontend: Vercel, asociado al dominio adm.itecelgs.com (dominio corporativo raíz itecelgs.com).
• Backend as a Service (BaaS): Supabase (PostgreSQL 15+).
  • Base de Datos Relacional: Modelado relacional multi-inquilino (row-level security).
  • Autenticación: Supabase Auth (correo/contraseña, tokens JWT, sesiones seguras).
  • Seguridad en Datos: Políticas de RLS (Row Level Security) nativas por rol y condominio.
  • Lógica de Servidor: Funciones PL/pgSQL, Triggers de base de datos (BEFORE/AFTER) y Procedimientos Almacenados (RPC).
  • Serverless Compute: Supabase Edge Functions (entorno Deno / TypeScript).
  • Almacenamiento de Archivos: Supabase Storage (comprobantes, archivos de cartelera, respaldos).
• Servicio de Correo Transaccional: Resend (invitaciones a residentes, cobranza masiva, resúmenes, códigos OTP).

---

2. Responsabilidades: Frontend vs Backend

Siguiendo el principio rector "El servidor manda; lo local es contingencia" (R6 / ADR-001):

Capa	Componente	Responsabilidades Principales
Frontend	React SPA (src/)	- Renderizado visual, diseño responsivo y UX interactiva. - Enrutamiento cliente (App.tsx, navegación por pestañas/vistas). - Manejo de estado en memoria y persistencia local de contingencia (localStorage). - Validaciones UX preventivas (deshabilitar botones, pre-cálculos visuales). - Tour interactivo de inducción y modales de operación.
Backend	PostgreSQL + RLS	- Autoridad final e inapelable de negocio y datos. - Aplicación estricta de políticas de acceso mediante RLS. - Validación de topes y cuotas por licencia mediante Triggers. - Registro forense no repudiable en audit_log con JWT verificado. - Integridad referencial (FOREIGN KEY, CASCADE / RESTRICT).
Backend	Edge Functions (supabase/functions/)	- Procesamiento seguro con Service Role protegido. - Generación y validación de tokens OTP temporales. - Integración con la API REST de Resend para despacho masivo. - Filtro de dominios en solicitudes demo. - Generación de plantillas HTML responsivas para correos.
Infraestructura	Vercel & Supabase	- Vercel: CDN global, compresión de bundles, HTTPS perimetral. - Supabase: Cluster administrado de Postgres, pool de conexiones PgBouncer.

---

3. Diagrama de Arquitectura General

---

4. Cadena de Identidad y Resolución de Contextos

La autenticación y autorización en ITECEL ADM no se limita a un rol estático: un usuario puede ser administrador de un condominio, inquilino en otro, o superadmin global.

---

5. Hallazgo Crítico: Vínculos por Email vs UUID

Durante la inspección forense del código real (src/lib/auth.ts, src/lib/licenseService.ts y las tablas de datos) se confirma el siguiente descalce estructural:

El Descalce Identificado

1. La tabla licenses vincula al usuario por la columna email (TEXT), no por user_id (UUID).
   La consulta canónica de verificación de licencias ejecuta:

   supabase.from('licenses').select('*').ilike('email', normalizedEmail);

2. La tabla housing_units vincula a los residentes mediante contact_email o dentro de estructuras JSON en la columna contacts, no por una clave foránea hacia auth.users(id).

Impacto y Relación con la Deuda Técnica 10.2 (D-NUEVA-2)

• Riesgo: Si un usuario o administrador solicita cambiar su correo electrónico en auth.users, su user_id permanece idéntico pero su dirección de correo muta.
• Consecuencia: Al cambiar el email en auth.users sin una migración orquestada y transaccional sobre todas las tablas satélites:
  • El usuario pierde el acceso a su licencia (la consulta .ilike('email', nuevoEmail) retornará vacío).
  • El usuario pierde el vínculo a sus departamentos/unidades en el directorio residencial.
  • La cuenta queda en estado "huérfano" o degradada a usuario sin contexto.
• Estado de Deuda: Documentada formalmente en docs/TECHNICAL_DEBT.md (Sección 10, Ítem 10.2 / D-NUEVA-2). Toda intervención sobre el flujo de actualización de correo debe abordar de forma atómica: auth.users + app_users + licenses + housing_units.

---

6. Referencias a Documentación Complementaria

Para profundizar en áreas específicas de la arquitectura, consultar los documentos dedicados:

• Respaldos y Persistencia Central:
  Consulte [docs/ARQUITECTURA-RESPALDOS-Y-GOBERNANZA.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/ARQUITECTURA-RESPALDOS-Y-GOBERNANZA.md) para el esquema de la tabla central_backups, políticas RLS de snapshots y retención.
• Mapeo Relacional de Módulos y Tablas:
  Consulte [docs/module-table-map.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/module-table-map.md) para el catálogo topológico de tablas y relaciones de clave foránea.
• Reglas de Desarrollo y Protocolo Operativo:
  Consulte [docs/GOBERNANZA.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/GOBERNANZA.md).
• Procedimientos Operativos de Despliegue y Diagnóstico:
  Consulte [docs/RUNBOOK.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/RUNBOOK.md).
• Registro de Decisiones Arquitectónicas (ADRs):
  Consulte [docs/DECISIONES.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/DECISIONES.md).
• Hoja de Ruta del Proyecto:
  Consulte [docs/ROADMAP.md](file:///c:/Users/Admin/ITECEL-adm/ITECEL-ADM/docs/ROADMAP.md).