# Arquitectura y Stack Tecnológico - EFINTEL ERP

Este documento detalla la arquitectura técnica elegida para el desarrollo, escalabilidad y mantenimiento del ERP de EFINTEL. La selección del stack se basa en mantener una alta velocidad de desarrollo, aprovechando las capacidades asíncronas de Python moderno y evitando la sobrecarga de mantener un frontend y backend separados (SPA).

---

## 1. Stack Backend (Core)

### Framework: Django 6.1 (Modo Asíncrono)
Mantenemos Django como pilar fundamental por su ORM, su panel de administración y su sistema de autenticación integrado.
- **Asincronismo (`async def`)**: Dado que corremos sobre un servidor ASGI, utilizaremos vistas asíncronas para operaciones que requieran alta concurrencia o tiempos de espera I/O (lectura de BD masiva, llamadas a APIs externas).
- **Programación Orientada a Objetos (POO)**: Todas las vistas de la aplicación deben basarse en *Class-Based Views* (CBV) para aprovechar la herencia y los Mixins (ej. `RoleRequiredMixin`).

### API REST: Django Ninja
Para la comunicación interna del sistema y futuras integraciones de terceros.
- Reemplaza a Django REST Framework (DRF).
- Tipado estricto y validación automática mediante **Pydantic**.
- Soporte nativo para rutas asíncronas, lo que incrementa el rendimiento.

### Tareas en Segundo Plano: Celery + Redis
Para no bloquear el hilo de ejecución principal (ej. la interfaz del usuario), delegamos las tareas pesadas:
- Generación de reportes PDF / Excel masivos.
- Sincronización y cálculo de planillas de sueldos.
- Envío masivo de correos de notificación.

### WebSockets: Django Channels
Para actualizaciones en tiempo real (ej. cuando otro usuario aprueba un gasto o notificaciones del sistema), respaldado por Redis.

---

## 2. Stack Frontend (El patrón HDA)

Para evitar la complejidad de construir un Single Page Application (SPA) con React o Vue, adoptaremos el patrón **HDA (HTMX + Django + Alpine.js)**. 

### HTMX
- **Propósito**: Realizar peticiones AJAX, filtros dinámicos, paginación y mutaciones del DOM sin escribir JavaScript.
- **WebSockets**: Utilizaremos la extensión `htmx-ws` para inyectar fragmentos HTML directamente al DOM cuando Channels emita un evento, eliminando el parseo manual de JSON en JS.

### Alpine.js
- **Propósito**: Manejo del estado efímero del lado del cliente.
- Casos de uso: Modales, menús desplegables (dropdowns), alertas (toasts), y pestañas (tabs). Sustituye por completo al código espagueti en Vanilla JS o jQuery.

### Tailwind CSS (Sugerido)
- **Propósito**: Sistema de diseño basado en utilidades. 
- Permite estilizar componentes directamente en los templates de Django sin mantener un archivo `style.css` gigante y difícil de escalar.

### Formularios: `django-widget-tweaks`
- Herramienta para inyectar clases CSS (como las de Tailwind o Bootstrap) directamente en los campos del formulario desde el HTML, eliminando la necesidad de scripts globales que mutan el DOM (`MutationObserver`).

---

## 3. Infraestructura y Despliegue

### Base de Datos y Storage: Supabase
Migramos de servicios locales a servicios administrados en la nube para garantizar disponibilidad y backups automáticos.
- **PostgreSQL**: Base de datos principal conectada mediante un *Connection Pooler* transaccional.
- **S3 Storage**: Almacenamiento en la nube (vía `django-storages` y `boto3`) para evidencias, facturas y comprobantes, garantizando que el contenedor Docker sea *stateless* (sin estado local).

### Servidor de Aplicaciones: Gunicorn + Uvicorn
- Para producción, reemplazaremos la ejecución directa de Daphne por **Gunicorn** usando `UvicornWorker`. Esto permite levantar múltiples procesos *workers* que aprovechan mejor los núcleos del servidor y se reinician automáticamente si fallan.

### Caché: Redis
- Además de ser el broker de Celery y Channels, habilitaremos Redis como el backend de la variable `CACHES` en Django. Esto permite almacenar en memoria resultados de consultas pesadas (como los KPIs del Dashboard) reduciendo la carga sobre Supabase.

### Integración Continua (CI/CD)
- **GitHub Actions**: Implementación de un pipeline que ejecute pruebas automáticas, verifique la calidad del código (Linting) y construya la imagen de Docker en cada Push a la rama `main`.

---

## 4. Hoja de Ruta (Roadmap de Implementación)

1. **Fase 1: Estabilización de Infraestructura**
   - [ ] Conectar definitivamente Supabase (DB + Storage) mediante el `.env`.
   - [ ] Habilitar Redis como motor de Caché en Django.
   - [ ] Cambiar el servidor de desarrollo a Gunicorn/Uvicorn para producción.

2. **Fase 2: Refactorización Frontend (HDA)**
   - [ ] Instalar HTMX y configurarlo en `base.html`.
   - [ ] Instalar `django-widget-tweaks` para refactorizar los formularios.
   - [ ] Migrar el flujo de WebSockets en JS nativo hacia la extensión `htmx-ws`.

3. **Fase 3: Optimización Backend**
   - [ ] Implementar la primera tarea en segundo plano con Celery (ej. Exportar CSV).
   - [ ] Migrar el Dashboard a vistas asíncronas (`async def`) para acelerar la carga de KPIs.