# Manual Técnico: GanttScrum Pro

## 1. Arquitectura del Sistema
El sistema GanttScrum Pro está construido sobre una arquitectura cliente-servidor moderna:
- **Backend:** Desarrollado en Python utilizando el framework **FastAPI**. Es altamente asíncrono y de alto rendimiento.
- **Base de Datos:** **PostgreSQL / MySQL / SQLite** administrada mediante el ORM SQLAlchemy asíncrono.
- **Frontend:** Arquitectura de "Vanilla Web" (HTML5, CSS3, Vanilla JavaScript) garantizando la máxima ligereza y carga rápida.

## 2. Tecnologías y Librerías Principales
- **FastAPI & Uvicorn:** Manejo de rutas RESTful, inyección de dependencias y servidor ASGI.
- **DHTMLX Gantt (GPL):** Motor principal para la renderización del cronograma interactivo.
- **Chart.js:** Utilizado para métricas en el Dashboard y Burndown Chart.
- **SortableJS:** Drag & Drop en el tablero Kanban.
- **JWT & MFA/2FA:** Autenticación segura con tokens JWT y verificación en dos pasos vía correo electrónico.
- **Cortafuegos WAF / GeoIP:** Middleware de seguridad perimetral para filtrado por país e IPs/CIDR con caché en base de datos (`geo_ip_rules` y `ip_geo_cache`).

## 3. Estructura de la Base de Datos
- `companies`: Gestión Multi-tenant (aislamiento por empresas).
- `users`: Gestión de autenticación, empresa asignada y 2FA.
- `roles` y `user_roles`: Control de acceso basado en roles (Super Administrador, Administrador, Miembro, etc.).
- `projects` y `project_members`: Entidades principales de gestión de proyectos.
- `kanban_columns` y `tasks`: Flujo de trabajo, estados, fechas e integraciones WBS.
- `task_links`: Precedencias lógicas del diagrama de Gantt.
- `audit_logs`: Trazabilidad completa de acciones de usuarios segregada por empresa con soporte de purga y exportación CSV.
- `geo_ip_rules`: Políticas de acceso geográfico y listas blancas/negras de IPs.
- `ip_geo_cache`: Caché local de resoluciones de geolocalización IP para latencia ultrabaja (<1ms).
- `system_settings`: Claves de configuración dinámica del sistema (WAF, 2FA, backups).

## 4. Módulo de Seguridad Perimetral y Cortafuegos GeoIP
### 4.1. Jerarquía de Políticas
1. **Super Administrador (Techo Máximo):** Define si el cortafuegos está activo (`geo_blocking_enabled`), el modo (`whitelist` o `blacklist`) y los países globales autorizados (ej: solo Chile `CL`).
2. **Empresa / Tenant (Excepciones):** Puede definir listas blancas/negras de IPs para sus sucursales u oficinas, y si el Superadmin habilita `geo_allow_company_exceptions`, puede habilitar países adicionales para sus colaboradores remotos.

### 4.2. Middleware de Intercepción
El middleware asíncrono `geoip_firewall_middleware` en `main.py` intercepta cada petición:
1. Extrae la IP del cliente (considerando cabeceras de proxy inverso como `CF-Connecting-IP`, `X-Forwarded-For`, `X-Real-IP`).
2. Valida si la IP pertenece a rangos privados/locales (`127.0.0.1`, `10.0.0.0/8`, `192.168.0.0/16`, etc.) otorgando pase inmediato.
3. Evalúa listas blancas y listas negras directas de IP y subredes CIDR.
4. Consulta el país en `ip_geo_cache` o consulta la API de geolocalización y almacena el resultado en caché.
5. Emite respuesta HTTP 403 con plantilla visual enriquecida o JSON en caso de bloqueo.

## 5. Despliegue y Mantenimiento
- **Servidor:** Compatible con Ubuntu en Proxmox, Servidores VPS y entornos cPanel.
- **Systemd:** Servicio backend `ganttscrum.service` gestionable con `systemctl`.
- **Nginx / Apache:** Reverse proxy sirviendo la carpeta estática `frontend/` y redirigiendo `/api` al backend.