Arquitectura del Sistema
Visión General
Lean Collection System (LCS) es una aplicación web de gestión de cobranza desplegada en Azure Container Apps. Utiliza una arquitectura de microservicios ligera con dos contenedores principales (web + worker), una base de datos SQL Server, y almacenamiento de archivos en Azure Blob Storage.
Componentes de Infraestructura
| Componente | Servicio Azure | Propósito |
|---|---|---|
| Web App | Container Apps | Aplicación principal Next.js |
| Worker | Container Apps (interno) | Procesamiento en background |
| Base de Datos | Azure SQL Server | Almacenamiento de datos |
| Archivos | Blob Storage | Archivos importados y exportados |
| Registry | Container Registry | Imágenes Docker |
| Documentación | Static Web Apps | Sitio Docusaurus |
| DNS | Custom domains | admin.recuperacionintegral.com |
Capas de la Aplicación
1. Edge Runtime — Proxy (src/proxy.ts)
El proxy es el primer punto de contacto para cada request. Se ejecuta en el Edge Runtime de Next.js para latencia mínima.
Responsabilidades:
- Verificar que el usuario esté autenticado (JWT válido)
- Evaluar permisos de acceso a la página desde el token JWT (sin consultas a DB)
- Controlar timeout por inactividad (30 min default)
- Forzar cambio de contraseña si está expirada (>60 días)
- Redirigir a login si la sesión es inválida
:::info Performance Al evaluar permisos desde el JWT directamente, el proxy no necesita consultar la base de datos en cada request, logrando latencia menor a 5ms por evaluación. :::
2. Node Runtime — Server Components + API Routes
Server Components:
- Renderizado server-side de páginas del dashboard
- Consultas a DB mediante Prisma para datos iniciales
- Filtrado de sidebar según permisos del usuario
API Routes:
- Lógica de negocio para CRUD operations
- Validación de permisos con
requirePermission() - Manejo de importaciones/exportaciones
- Triggers al Worker via HTTP
3. Client Components — UI Interactiva
- React 19 con Server Components por defecto
- shadcn/ui para componentes de interfaz (basado en Radix UI)
- Tailwind CSS para estilos
- Formularios, tablas interactivas, modales, progress bars
4. Worker Service — Background Processing
Container independiente que procesa tareas asíncronas:
Características del Worker:
- Escala a cero cuando no hay trabajo (ahorro de costos)
- Se despierta vía HTTP trigger desde la Web App
- Procesa jobs de forma inmediata (sin polling/delay)
- Recovery automático de jobs interrumpidos al iniciar
- Graceful shutdown en SIGTERM (persiste progreso)
Patrón de Comunicación Web ↔ Worker
Escalamiento
| Container | Min Réplicas | Max Réplicas | Trigger |
|---|---|---|---|
| Web App | 0 | 10 | HTTP traffic |
| Worker | 0 | 5 | HTTP concurrent requests |
:::tip Scale-to-Zero Ambos containers escalan a cero en horarios de inactividad, minimizando costos. El Worker solo se activa cuando hay jobs pendientes. :::
Flujo de Datos Completo
Tecnologías Clave
| Capa | Tecnología | Versión | Propósito |
|---|---|---|---|
| Frontend | Next.js | 15 | Framework React full-stack |
| UI | shadcn/ui + Radix | — | Componentes accesibles |
| Estilos | Tailwind CSS | 4 | Utility-first CSS |
| ORM | Prisma | 6 | Type-safe database access |
| Auth | NextAuth.js | v5 | Autenticación JWT |
| DB | SQL Server | Azure SQL | Base de datos relacional |
| Storage | Azure Blob | — | Archivos binarios |
| Runtime | Node.js | 20+ | Server runtime |
| Container | Docker | — | Containerización |
| CI/CD | PowerShell | — | Scripts de despliegue |