Clone
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Visión General del Sistema
Diagrama de arquitectura
┌─────────────────────────────────────────────────────────────────┐
│ FLUTTER APP (Mobile) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Login Screen │ │ Recycling Guide │ │
│ │ (Persona C) │ │ (Persona D) │ │
│ │ │ │ │ │
│ │ - Auth JWT │ │ - 4 categorías │ │
│ │ - Alta usuario │ │ - Búsqueda │ │
│ └────────┬─────────┘ │ - Offline │ │
│ │ └──────────────────┘ │
│ │ │
│ ┌────────▼──────────────────────────────────┐ │
│ │ ETA Home Screen │ │
│ │ (Persona C) │ │
│ │ │ │
│ │ - Ventana horaria (7:20 pm - 7:35 pm) │ │
│ │ - WebSocket listener │ │
│ │ - Notificaciones push │ │
│ │ - Riverpod state management │ │
│ └────────┬──────────────────────────────────┘ │
│ │ │
└───────────┼─────────────────────────────────────────────────────┘
│
│ HTTP REST + WebSocket
│
┌───────────▼─────────────────────────────────────────────────────┐
│ FASTAPI BACKEND (Python) │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Auth Module │ │ ETA + Simulator │ │
│ │ (Persona A) │ │ (Persona B) │ │
│ │ │ │ │ │
│ │ - JWT tokens │ │ - Simulador │ │
│ │ - RBAC │ │ - WebSocket │ │
│ │ - Alta domicilio│ │ - Notificaciones│ │
│ │ - Validar zona │ │ - ETA calc │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ SQLite DB │ │
│ │ │ │
│ │ - users │ │
│ │ - addresses │ │
│ │ - rutas │ │
│ │ - puntos_ruta │ │
│ │ - truck_status │ │
│ │ - notificaciones│ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
Principios de diseño
🔒 Privacidad por Diseño
- El usuario NO ve el mapa completo de la ruta
- Solo recibe: ETA + ventana horaria + mensaje de acción
- El backend nunca envía coordenadas GPS al cliente
- Visión de "túnel": solo su domicilio, cero colonias vecinas
🏗️ Clean Architecture
- Dominio: Entidades puras (Ruta, PuntoRuta, Notificación)
- Data: Repositories + Datasources (SQLite, JSON local)
- Use Cases: Lógica de negocio aislada
- Presentation: UI (Flutter) y API (FastAPI) desacopladas
🔄 Separación de responsabilidades
- Persona A: Gestión de identidad y domicilios
- Persona B: Simulación de ruta y notificaciones en tiempo real
- Persona C: Experiencia de usuario principal (login + ETA)
- Persona D: Módulo educativo offline (guía de residuos)
Flujos principales
1. Alta de usuario (Persona A)
Usuario → POST /register → Backend valida email/teléfono
→ Crea usuario en BD
→ Retorna JWT token
Usuario → POST /addresses → Backend valida lat/lng
→ Asigna route_id según zona
→ Guarda domicilio
2. Consulta de ETA (Persona B + C)
Flutter → GET /eta/{address_id} → Backend calcula distancia
→ Devuelve ventana horaria
→ Flutter muestra "7:20 pm – 7:35 pm"
3. Notificación en tiempo real (Persona B + C)
Flutter → WS connect /ws/{address_id}
Backend Simulador → cada 10s actualiza truck_status
→ si ETA ≤ 10 min → broadcast WebSocket
Flutter → recibe JSON evento → muestra alerta push
4. Guía de separación (Persona D)
Usuario → navega a /guia → Lee assets/recycling_guide.json
→ Renderiza 4 categorías
→ Buscador offline funciona sin backend
Tecnologías clave
| Capa | Tecnología | Por qué |
|---|---|---|
| Frontend | Flutter 3.44 | Multiplataforma, UI rápida |
| Estado | Riverpod 2.6 | Type-safe, sin BuildContext |
| Backend | FastAPI 0.111 | Async nativo, WebSocket, validación Pydantic |
| BD | SQLite | Ligero, sin servidor externo, suficiente para MVP |
| WebSocket | uvicorn + APScheduler | Push real-time sin polling |
Siguiente paso
Lee las arquitecturas detalladas: