11 KiB
Mi Ruta Limpia
Sistema de notificación inteligente y privada de recolección de residuos
Hackathon LINCEHACK · Gobierno de Celaya · 2026
Descripción
Mi Ruta Limpia es una aplicación móvil que resuelve un problema cotidiano en Celaya: la ciudadanía no sabe con certeza cuándo pasará el camión recolector por su domicilio, lo que genera basura acumulada en la vía pública, problemas de salud y molestias vecinales.
La solución ofrece estimaciones de llegada por ventana horaria, notificaciones de cambios operativos, reportes ciudadanos con folio oficial y educación ambiental integrada — todo bajo un principio innegociable de privacidad por diseño: el ciudadano solo ve la información de su zona, nunca la ubicación del camión ni las rutas de terceros.
Roles y funcionalidades
Ciudadano
- Registro de múltiples domicilios con etiquetas personalizadas
- ETA por ventana horaria (ej. "Entre 7:20 y 7:35") sin coordenadas del camión
- Barra de progreso de ruta sin exponer ubicación exacta
- Confirmación de paso del camión con opción de deshacer
- Calificación del servicio (1–5 estrellas)
- Reportes ciudadanos con folio único (
MRL-YYYYMMDD-XXXXXX) exportables como comprobante - Módulo de educación ambiental: 4 categorías, datos de impacto y puntos de acopio
Empleado operativo
- Registro de incidencias operativas (falla mecánica, obstáculo, accidente, etc.) con folio
OP-YYYYMMDD-XXXXXX - Seguimiento de racha de puntualidad con sistema de bonos ($50 MXN/día puntual)
- Horario preestablecido con descansos técnicos
- Sin acceso a reportes ciudadanos (403 Forbidden por diseño)
Administrador
- Dashboard con KPIs en tiempo real: usuarios activos, domicilios, reportes en 24 h, calificación promedio
- Gestión del ciclo de vida de reportes:
PENDIENTE → EN_PROCESO → RESUELTO → CERRADO - Administración de usuarios y cambio de roles
- Vista de flotilla (62 camiones) y feedback ciudadano agregado
Stack tecnológico
| Capa | Tecnologías |
|---|---|
| Backend | Python 3.13, FastAPI 0.115, SQLAlchemy 2.0, SQLite, JWT (python-jose), bcrypt, Pydantic v2, PyTZ |
| Frontend | React Native 0.74, Expo SDK 51, React Navigation 6, expo-linear-gradient, AsyncStorage |
| DevOps | Watchman, Metro bundler (Expo CLI) |
La base de datos es SQLite con capacidad de migración a PostgreSQL sin cambios en la capa de servicio.
Arquitectura
┌──────────────────────────────────────────────────────────────────┐
│ FRONTEND (Expo) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Ciudadano │ │ Empleado │ │ Admin │ │
│ │ 5 tabs │ │ 3 tabs │ │ 4 tabs │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ fetch + AsyncStorage (JWT) │
└──────────────────────────┼───────────────────────────────────────┘
│ HTTPS REST
▼
┌──────────────────────────────────────────────────────────────────┐
│ BACKEND (FastAPI) │
│ │
│ /api/v1/auth — login, registro, /me │
│ /api/v1/addresses — CRUD de domicilios + geo-routing │
│ /api/v1/eta — cálculo de ETA privado │
│ /api/v1/reports — reportes ciudadanos │
│ /api/v1/admin — restringido a ADMIN │
│ /api/v1/staff — restringido a EMPLEADO/ADMIN │
│ │
│ Middleware: JWT (HTTPBearer) · RBAC · CORS │
└──────────────────────────┬───────────────────────────────────────┘
│
┌───────────┴────────────┐
▼ ▼
┌──────────────┐ ┌────────────────┐
│ SQLite │ │ routes.json │
│ │ │ (mock GPS) │
│ users │ │ │
│ addresses │ │ 15 rutas con │
│ reports │ │ waypoints + │
│ op_reports │ │ timestamps │
│ ratings │ └────────────────┘
│ trucks │
└──────────────┘
Para el análisis completo de decisiones técnicas, ver docs/ARQUITECTURA.md.
Instalación
Requisitos previos
- Node.js 20 LTS (no compatible con Node 22+)
- Python 3.11 o superior
- macOS o Linux (probado en macOS con Xcode + iOS Simulator)
Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Poblar la base de datos con datos demo
python seed_massive.py
# Iniciar el servidor
uvicorn main:app --reload --host 0.0.0.0 --port 8000
La API queda disponible en http://localhost:8000. La documentación interactiva en http://localhost:8000/docs.
Frontend
cd frontend
ulimit -n 65536 # macOS: ampliar límite de file descriptors
npm install
npx expo start --clear
Presiona i para iOS Simulator, w para web, o escanea el QR con Expo Go.
La URL del backend se configura en
frontend/src/constants/config.js. Actualízala si tu IP local difiere de10.82.68.125.
Para la guía paso a paso y troubleshooting, ver docs/INSTALACION.md.
Credenciales de demo
| Rol | Contraseña | |
|---|---|---|
| Ciudadano | demo@celaya.gob.mx |
Celaya2026 |
| Empleado | empleado@celaya.gob.mx |
Empleado2026 |
| Administrador | admin@celaya.gob.mx |
Admin2026 |
La base de datos de demo incluye 202 usuarios, 302 domicilios, 280 reportes ciudadanos, 150 reportes operativos, 220 calificaciones y 62 camiones generados con seed_massive.py.
Privacidad por diseño
Este principio es el núcleo del proyecto y responde directamente al reto planteado en el hackathon.
| Riesgo | Mitigación implementada |
|---|---|
| Ciudadanos persiguiendo camiones | El endpoint /eta/address/:id devuelve únicamente: status, mensaje, eta_minutes, window_start/end y progress%. Sin coordenadas. |
| Acceso a rutas de otros usuarios | El backend valida que Address.user_id == JWT.user_id en cada solicitud. |
| Exposición de información operativa | Las rutas de otros camiones son inaccesibles incluso con manipulación del request. |
| Incentivo a perseguir camiones | La interfaz incluye el aviso explícito: "Por tu seguridad, no persigas al camión." |
| Datos sensibles | Contraseñas con bcrypt · JWT firmado con HS256 · sin PII en logs. |
Estructura del proyecto
mi-ruta-limpia/
├── README.md
├── docs/
│ ├── ARQUITECTURA.md # Decisiones técnicas y algoritmo ETA
│ ├── MANUAL_USUARIO.md # Guía visual por pantalla
│ ├── API.md # Referencia REST completa
│ ├── INSTALACION.md # Setup y troubleshooting
│ └── PRESENTACION.md # Script de demo para el pitch
│
├── backend/
│ ├── main.py # Entry point, CORS y routers
│ ├── requirements.txt
│ ├── seed.py # Seed básico (3 usuarios)
│ ├── seed_massive.py # Seed completo (200+ usuarios)
│ └── app/
│ ├── config.py
│ ├── database.py
│ ├── models/ # User, Address, Report, OperationalReport, Truck, ServiceRating
│ ├── schemas/ # Pydantic v2
│ ├── routers/ # auth, addresses, eta, reports, admin, staff
│ ├── services/ # auth_service, eta_service
│ └── data/routes.json # 15 rutas mock
│
└── frontend/
├── App.js
├── index.js
├── package.json
├── app.json
├── assets/
└── src/
├── constants/ # colors, config
├── context/ # AuthContext (JWT + role)
├── navigation/ # AppNavigator (routing por rol)
├── components/ # AppHeader, GoogleGIcon
├── services/api.js # fetch + interceptors
└── screens/
├── auth/ # Login, Register
├── HomeScreen.js
├── SchedulesScreen.js
├── ReportsScreen.js
├── ProfileScreen.js
├── EducationScreen.js
├── staff/ # StaffDashboard, StaffReports
└── admin/ # AdminDashboard, AdminReports, AdminUsers, AdminProfile
Documentación
| Documento | Audiencia | Contenido |
|---|---|---|
docs/ARQUITECTURA.md |
Jueces técnicos | Decisiones de diseño, algoritmo ETA, RBAC, simulación de flotilla |
docs/MANUAL_USUARIO.md |
Usuarios finales | Guía visual por pantalla y flujo completo |
docs/API.md |
Desarrolladores | Referencia REST con ejemplos |
docs/INSTALACION.md |
Operaciones | Setup paso a paso y troubleshooting |
docs/PRESENTACION.md |
Equipo presentador | Script de demo para los 5–10 min del pitch |
Licencia
Proyecto desarrollado con fines educativos en el marco del hackathon LINCEHACK 2026. Los datos de Celaya son referenciales.
Celaya, es la esperanza.