ATLAS/docs/plans/2026-01-21-adan-design.md

Sistema de Monitoreo de ATLAS GPS + IA

Resumen Ejecutivo

Sistema completo de monitoreo de atlas vehiculares con rastreo GPS en tiempo real, video streaming, integración con dispositivos Meshtastic, y app móvil para conductores. Diseñado para escala pequeña (1-20 vehículos) con arquitectura preparada para crecimiento futuro.

Fecha: 2026-01-21 Estado: Pendiente de aprobación

---

Decisiones de Diseño

Aspecto	Decisión
Escala inicial	Pequeña (1-20 vehículos)
Dispositivos GPS	Traccar-compatible (protocolo abierto)
Meshtastic	Módulo experimental/opcional
App móvil	React Native para conductores
Despliegue	VM única en Proxmox (Ubuntu 22.04)
Acceso web	Cloudflare Zero Trust Tunnel
GPS hardware	Puerto TCP 5055 abierto
IA/ML	Básico ahora, arquitectura preparada
Backend	Python/FastAPI
Frontend	React + TypeScript + TailwindCSS
Base de datos	PostgreSQL + TimescaleDB
Cache	Redis
Video	MediaMTX (RTSP/WebRTC/HLS)
Usuarios	Solo admin (sin multi-tenant)

---

Arquitectura General

┌─────────────────────────────────────────────────────────────────┐
│                    PROXMOX - VM ÚNICA                           │
│                   (Ubuntu 22.04 LTS)                            │
│                   RAM: 4-8GB | CPU: 4 cores                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              CLOUDFLARED (Tunnel)                        │   │
│  │         atlas.tudominio.com → localhost              │   │
│  └─────────────────────┬───────────────────────────────────┘   │
│                        │                                        │
│         ┌──────────────┴──────────────┐                        │
│         ▼                             ▼                        │
│  ┌───────────┐                 ┌───────────┐                  │
│  │  React    │                 │  FastAPI  │                  │
│  │  Frontend │                 │  Backend  │                  │
│  │  :3000    │                 │  :8000    │                  │
│  └───────────┘                 └─────┬─────┘                  │
│                                      │                         │
│                        ┌─────────────┤                        │
│                        ▼             ▼                        │
│  ┌───────────┐  ┌─────────────────────────┐                  │
│  │  Traccar  │  │ PostgreSQL + TimescaleDB │                  │
│  │  Server   │  │ Redis                    │                  │
│  │  :5055 ◄──┼──┼─────────────────────────┘                  │
│  └─────┬─────┘  │                                             │
│        │        │                                              │
└────────┼────────┼──────────────────────────────────────────────┘
         │        │
         ▼        │
   ┌──────────┐   │
   │ PUERTO   │   │ Cloudflare Tunnel (HTTPS)
   │ TCP 5055 │   │
   │ (abierto)│   │
   └────┬─────┘   │
        │         │
        ▼         ▼
   📡 GPS      📱 App    📻 Meshtastic    💻 Dashboard
   Hardware    Móvil      (opcional)       Admin

---

Modelo de Datos

Tablas Principales

• vehiculos - Información de vehículos
• conductores - Datos de conductores
• dispositivos - GPS y dispositivos asociados
• ubicaciones (HYPERTABLE) - Posiciones GPS
• viajes - Registro de viajes
• paradas - Paradas durante viajes
• alertas - Sistema de alertas
• geocercas - Zonas geográficas
• pois - Puntos de interés
• cargas_combustible - Registro de cargas
• mantenimientos - Programación de mantenimiento
• camaras - Cámaras de video
• grabaciones - Videos almacenados
• eventos_video - Eventos detectados en video
• mensajes - Comunicación admin-conductor
• configuracion - Configuración del sistema
• audit_log - Logs de auditoría

---

API Endpoints

Principales

/api/v1
├── /auth           → Autenticación JWT
├── /vehiculos      → CRUD vehículos
├── /conductores    → CRUD conductores
├── /ubicaciones    → Recepción GPS + WebSocket
├── /viajes         → Gestión y replay de viajes
├── /alertas        → Centro de alertas
├── /geocercas      → Gestión de geocercas
├── /pois           → Puntos de interés
├── /combustible    → Registro de cargas
├── /mantenimiento  → Programación servicios
├── /video          → Streaming y grabaciones
├── /reportes       → Generación de reportes
├── /meshtastic     → Integración mesh (opcional)
└── /configuracion  → Settings del sistema

/ws/v1
├── /ubicaciones    → Stream tiempo real
├── /alertas        → Notificaciones push
└── /video/{id}     → Señalización WebRTC

---

Interfaces de Usuario

Dashboard Web

• Login - Autenticación con tema oscuro
• Dashboard - KPIs, mapa resumen, alertas, actividad
• Mapa - Vista tiempo real con filtros y capas
• Flota - Cards/tabla de vehículos y conductores
• Detalle vehículo - Info completa, viajes, estadísticas
• Alertas - Centro de gestión de alertas
• Video - Grid de cámaras en vivo
• Grabaciones - Búsqueda y reproducción
• Viajes - Lista y replay con video sincronizado
• Geocercas - Editor visual en mapa
• Reportes - Generación y programación
• Configuración - Settings del sistema

App Móvil (Conductores)

• Login - Por teléfono + código
• Home - Estado, botón iniciar viaje, resumen
• Viaje activo - Mapa, próxima parada, controles
• Paradas - Registro con tipo y notas
• Combustible - Registro de cargas
• Mensajes - Comunicación con admin
• Emergencia - Botón SOS
• Perfil - Estadísticas y configuración
• Cámara - Dashcam opcional

---

Seguridad

• JWT con refresh tokens (24h / 7 días)
• API keys únicas por dispositivo
• Rate limiting (100 req/min general, 1 req/seg ubicaciones)
• Headers de seguridad (CSP, HSTS, X-Frame-Options)
• Passwords hasheados con bcrypt
• Datos sensibles encriptados (Fernet)
• Logs de auditoría completos
• Firewall UFW + Fail2ban
• Cloudflare WAF y DDoS protection

---

Despliegue

Requisitos Mínimos VM

• CPU: 4 cores
• RAM: 8 GB
• Disco Sistema: 60 GB SSD
• Disco Videos: 2 TB HDD
• OS: Ubuntu 22.04 LTS

Servicios

• atlas-api.service - Backend FastAPI
• atlas-web.service - Frontend React
• traccar.service - Servidor GPS
• mediamtx.service - Streaming video
• cloudflared.service - Tunnel Cloudflare
• postgresql.service - Base de datos
• redis.service - Cache

Puertos

• 5055/TCP (abierto) - GPS devices
• 5432 (interno) - PostgreSQL
• 6379 (interno) - Redis
• 8000 (interno) - API
• 3000 (interno) - Frontend
• 8554/8888/8889 (interno) - Video

---

Entregables

1. Código fuente completo (backend, frontend, mobile)
2. Scripts de instalación automatizada
3. Configuraciones de servicios
4. Documentación técnica completa
5. Guías de usuario (admin y conductor)
6. API Reference

---

Repositorio

URL: https://git.consultoria-as.com Nombre: atlas

---

Aprobación

• Arquitectura aprobada
• Modelo de datos aprobado
• Diseño de interfaces aprobado
• Plan de despliegue aprobado
• Listo para implementación