# 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