🔥 CERBERO - Sistema de Detección Temprana de Incendios

Warning

🚧 PROTOTIPO EN DESARROLLO 🚧

Este proyecto es actualmente un prototipo que está siendo reorganizado para facilitar su uso y despliegue. Los modelos de IA (Hades) no están incluidos en este repositorio por limitaciones de tamaño, por lo que el sistema no es funcional en este momento.

Estado actual:

• ✅ Arquitectura completa implementada
• ✅ Microservicios funcionales
• ⚠️ Modelos de IA pendientes de subir
• ⚠️ Sistema no funcional hasta completar la migración

Estamos trabajando en una versión completa y funcional. ¡Mantente atento! 🔄

"El guardián que nunca duerme" 🐕‍🦺

---

🌟 ¿Qué es Cerbero?

Cerbero es un sistema revolucionario de detección temprana de incendios que combina:

• 🤖 Inteligencia Artificial avanzada con múltiples modelos neurales (Hades v1-v8)
• 📷 Análisis visual en tiempo real mediante cámaras inteligentes
• 🌍 Monitoreo de calidad del aire con sensores IoT
• 🗺️ Visualización geográfica de alertas y zonas de riesgo
• ⚡ Respuesta inmediata ante detección de amenazas

Como el mítico perro de tres cabezas que guardaba el inframundo, Cerbero vigila incansablemente nuestros bosques y espacios naturales, detectando incendios antes de que se conviertan en catástrofes.

---

🏗️ Arquitectura del Sistema

graph TB
    subgraph "🌐 Frontend"
        A[Astro + React + TypeScript]
        B[Leaflet Maps]
        C[Tailwind CSS + Radix UI]
    end
    
    subgraph "⚖️ Load Balancer"
        D[HAProxy]
    end
    
    subgraph "🔧 Backend Services"
        E[Spring Boot - Main API]
        F[Spring Boot - Requests API]
    end
    
    subgraph "🧠 AI Workers"
        G[Hades v8 - Image Analysis]
        H[Air Quality Worker]
        I[Manager/Coordinator]
    end
    
    subgraph "💾 Data Layer"
        J[PostgreSQL + Citus]
        K[Redis Cache]
        L[Apache Kafka]
    end
    
    subgraph "🔐 Security"
        M[JWT Key Generator]
        N[Authentication]
    end
    
    A --> D
    D --> E
    D --> F
    E --> J
    F --> L
    L --> G
    L --> H
    L --> I
    G --> L
    H --> L
    I --> L
    E --> K
    F --> K
    M --> N
    N --> E
    N --> F

Loading

---

🚀 Características Principales

🔥 Detección Inteligente de Incendios

• 8 versiones del modelo Hades con arquitecturas CNN avanzadas
• Análisis multiescala con convoluciones dilatadas
• Residual connections para mejor precisión
• Detección en tiempo real con umbral configurable (>70-80%)

🌬️ Monitoreo de Calidad del Aire

• Análisis de 7 parámetros ambientales:
  • CO₂, PM2.5, CO, VOCs, O₃, NO₂, SO₂
• Predicción de riesgo basada en umbrales científicos
• Alertas tempranas por deterioro de calidad del aire

🗺️ Visualización Geoespacial

• Mapas interactivos con Leaflet
• Marcadores en tiempo real de cámaras y sensores
• Zonas de riesgo coloreadas por nivel de amenaza
• Historial de incidentes georreferenciados

🔐 Seguridad y Autenticación

• JWT tokens con rotación automática
• Autenticación de dispositivos IoT
• Encriptación end-to-end de comunicaciones
• Control de acceso por roles y permisos

---

🧠 Modelos de IA: La Familia Hades

Note

📁 Modelos no incluidos: Los archivos .pth de los modelos Hades (varios GB) no están en este repositorio. Se está trabajando en una solución para distribuirlos (Git LFS, releases, etc.).

🏛️ Hades v1-v3: Fundamentos

• Arquitectura CNN básica con BatchNorm y Dropout
• 3-4 capas convolucionales con MaxPooling
• Precisión: ~60-70%
• Framework: PyTorch

⚡ Hades v5-v7: Evolución

• Conexiones residuales para gradientes más estables
• 8 etapas de procesamiento con mayor profundidad
• Squeeze & Excitation blocks para atención selectiva
• Precisión: ~95-98%
• Framework: PyTorch

🚀 Hades v8: Estado del Arte

class Hades8(nn.Module):
    """
    Modelo avanzado con PyTorch:
    - Depthwise Separable Convolutions
    - Hybrid Attention (Channel + Spatial)
    - Denoising blocks
    - Bottleneck Residual connections
    """

• Arquitectura híbrida con atención multimodal
• Procesamiento multiescala (kernels 3x3, 5x5, 7x7)
• Denoise blocks para robustez en condiciones adversas
• Precisión teórica: >98% con <5% falsos positivos
• Framework: PyTorch con CUDA support
• Estado: 🚧 Pendiente de incluir en el repositorio

---

🔧 Stack Tecnológico

Frontend

Backend

AI/ML

Infrastructure

---

⚡ Instalación (Prototipo)

Important

🚨 ATENCIÓN: Este es un prototipo no funcional. Los modelos de IA no están incluidos.

🎯 Comando para probar la arquitectura:

bash start.bash

⚠️ Qué funcionará:

• ✅ Infraestructura completa (Docker containers)
• ✅ Base de datos y APIs
• ✅ Interfaz web (sin predicciones reales)
• ✅ Sistema de autenticación

❌ Qué NO funcionará:

• ❌ Detección de incendios (faltan modelos Hades)
• ❌ Análisis de imágenes con IA
• ❌ Predicciones reales

📋 Requisitos Previos

• 🐳 Docker y Docker Compose instalados
• 🖥️ 8GB RAM mínimo (16GB recomendado)
• 💾 20GB espacio libre en disco
• 🌐 Conexión a internet para descargar dependencias

---

🌟 Servicios Incluidos

Servicio	Puerto	Descripción
🌐 Frontend Web	:80	Interfaz principal de usuario
🔧 API Principal	:8080	Backend de autenticación y mapas
📡 API Peticiones	:8081	Gestión de cámaras y sensores
🗄️ PostgreSQL	:5432	Base de datos principal
🔄 Redis	:6379	Cache y gestión de claves
📨 Kafka	:9092	Cola de mensajes para IA
⚖️ HAProxy Stats	:8080/stats	Monitoreo del load balancer

---

🎮 Uso del Sistema

1️⃣ Registro de Dispositivos

# Las cámaras/sensores se auto-registran enviando:
POST /api/init
{
  "MAC": "AA:BB:CC:DD:EE:FF",
  "latitude": 40.4168,
  "longitude": -3.7038
}

2️⃣ Envío de Imágenes

# Las cámaras envían imágenes para análisis:
POST /api/guard
{
  "token": "jwt_token_dispositivo",
  "photos": ["base64_image1", "base64_image2"],
  "length": 2
}

3️⃣ Monitoreo de Calidad del Aire

# Los sensores envían datos ambientales:
POST /api/specter
{
  "token": "jwt_token_sensor",
  "datos": [CO2, PM25, CO, VOC, O3, NO2, SO2],
  "type": "air_quality"
}

4️⃣ Visualización en Tiempo Real

• 🗺️ Abre http://localhost en tu navegador
• 📊 Observa las detecciones en el mapa interactivo
• 🚨 Recibe alertas inmediatas de incendios
• 📈 Monitorea tendencias de calidad del aire

---

🔬 Arquitectura de Microservicios

🧠 Workers de IA

• ia_worker: Procesa imágenes RGB con modelos Hades
• ia_worker_air: Analiza datos de calidad del aire
• manager: Coordina y distribuye tareas

🔧 Backends

• cerbero_server: API principal (auth, usuarios, mapas)
• cerbero_backend: API de peticiones (cámaras, sensores)

💾 Datos

• db: PostgreSQL con extensión Citus para escalabilidad
• redis: Cache de sesiones y claves JWT
• kafka: Bus de mensajes para comunicación asíncrona

🔐 Seguridad

• keygenerator: Rotación automática de claves JWT
• sql_maker: Inicialización segura de esquemas

---

📊 Métricas de Rendimiento (Proyectadas)

Note

📈 Métricas teóricas: Estas métricas son proyecciones basadas en pruebas locales. El sistema completo aún no está en producción.

🎯 Precisión de Modelos (En Desarrollo)

• Hades v8: 98.2% precisión teórica, 4.1% falsos positivos
• Hades v7: 96.8% precisión teórica, 6.2% falsos positivos
• Air Quality: 94.5% precisión en predicción de riesgo

⚡ Rendimiento Esperado del Sistema

• Latencia objetivo: < 2 segundos
• Throughput objetivo: 1000+ imágenes/minuto
• Escalabilidad: Horizontal vía Kafka partitions
• Disponibilidad objetivo: 99.9% uptime con HAProxy

💾 Recursos Estimados

• RAM: 6-12GB en funcionamiento normal
• CPU: Utilización del 40-80% durante picos
• Storage: Crecimiento ~1GB/día con 100 cámaras

---

🔍 Monitoreo y Debugging

📊 Logs en Tiempo Real

# Ver logs de todos los servicios
docker compose logs -f

# Logs específicos del worker de IA
docker compose logs -f ia_worker

# Logs de la base de datos
docker compose logs -f db

🩺 Health Checks

# Estado general del sistema
curl http://localhost/api/status

# Estado de la API de peticiones  
curl http://localhost:8081/api/status

# Estadísticas de HAProxy
curl http://localhost:8080/stats

🐛 Debugging de Modelos

Los notebooks Jupyter en ia_models/hades/ permiten:

• 🔬 Probar arquitecturas de modelos
• 📊 Analizar métricas de performance
• 🎥 Simular detecciones (sin modelos reales)
• 🔧 Ajustar hiperparámetros

⚠️ Nota: Los modelos .pth no están incluidos, por lo que las predicciones reales no funcionan.

---

🌍 Potencial Impacto Ambiental

Note

🎯 Visión futura: Este es el impacto proyectado una vez que el sistema esté completamente funcional.

🌲 Potencial de Protección de Ecosistemas

• Detección temprana podría reducir área quemada en 80%
• Respuesta rápida salvaría miles de hectáreas anualmente
• Monitoreo continuo 24/7 sin intervención humana

📈 Objetivos de Impacto

• 🔥 Meta: Detectar incendios en fase inicial
• 🌳 Objetivo: Proteger 50,000+ hectáreas/año
• ⏱️ Target: 15 minutos tiempo promedio de detección
• 🎯 Meta: 95%+ precisión en condiciones reales

---

🤝 Contribuir al Proyecto

🚀 ¿Quieres mejorar Cerbero?

1. Fork el repositorio
2. Crea una rama para tu feature: git checkout -b feature/nueva-funcionalidad
3. Desarrolla tus cambios
4. Testea con bash start.bash
5. Commit: git commit -m "Añade nueva funcionalidad increíble"
6. Push: git push origin feature/nueva-funcionalidad
7. Pull Request y explica tus mejoras

🎯 Áreas de Contribución

• 🧠 Nuevos modelos de IA (Hades v9, v10...)
• 📱 Apps móviles para alertas
• 🌐 Integración con APIs meteorológicas
• 🔧 Optimizaciones de rendimiento
• 📚 Documentación y tutoriales

---

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

---

🙏 Agradecimientos

🎖️ Desarrollado por

• Equipo Cerbero - Visionarios de la detección temprana
• Comunidad Open Source - Por las herramientas increíbles

💡 Inspirado en

• 🔥 La necesidad urgente de proteger nuestros bosques
• 🤖 El poder de la inteligencia artificial para el bien
• 🌍 La visión de un mundo más seguro y sostenible

---

🔥 ¡Únete a la Revolución de la Detección de Incendios! 🔥

"Con Cerbero, cada segundo cuenta y cada bosque importa"

🌟 Dale una estrella • 🐛 Reporta un bug • 💬 Únete a Discord

---

Made with ❤️ and 🔥 by the Cerbero Team