# 🚛 BasuraApp — HackOnLinces 2026

Sistema de notificación inteligente y privada de recolección de residuos para la ciudadanía de Celaya, Guanajuato.

## 🎯 Problemática

Los ciudadanos no saben con certeza cuándo pasará el camión recolector, lo que genera basura en la calle fuera de horario, problemas de salud pública y fauna nociva.

## ✅ Solución

App móvil que notifica la hora aproximada de llegada del camión **sin exponer la ruta completa**, bajo un principio de **Privacidad por Diseño**.

## 🏗️ Arquitectura
Frontend (React Native / Expo)
↓ JWT + HTTPS
API Gateway + Auth (FastAPI)
↓ RBAC por domicilio
┌─────────────────────────────┐
│  ETA Service  │  Simulator  │
│  (cálculo)    │  (cron job) │
└─────────────────────────────┘
↓
PostgreSQL — Usuario → Domicilio → Zona → Ruta

## 🔒 Privacidad por Diseño

- El usuario **solo ve** la ventana de llegada de su ruta asignada
- La API valida en cada request que el `usuario` solo accede a su `domicilio`
- **Prohibido**: mapa en tiempo real, rastreo del camión, explorar rutas ajenas
- Mensajería preventiva: la app desalienta sacar basura fuera de horario

## 📱 Funcionalidades MVP

- [x] Registro e inicio de sesión con JWT
- [x] Alta de domicilio con validación de colonia
- [x] ETA con ventana de llegada (±7 min)
- [x] Simulador de rutas (cron job cada 2 min)
- [x] 3 eventos de notificación: ROUTE_START, TRUCK_PROXIMITY, ROUTE_COMPLETED
- [x] Guía de separación de residuos (funciona offline)
- [x] RBAC — cada usuario solo consulta su ruta
- [X] Buzón de reportes (en desarrollo)
- [ ] Notificaciones push FCM (en desarrollo)

## 🛠️ Stack Tecnológico

| Capa | Tecnología |
|------|-----------|
| Frontend | React Native + Expo SDK 54 |
| Backend | Python 3.12 + FastAPI |
| Auth | JWT (python-jose + passlib) |
| Base de datos | PostgreSQL + SQLAlchemy |
| Simulador | APScheduler (cron job) |
| Control de versiones | Gitea (git.onlinces.net) |

## 🚀 Cómo correr el proyecto

### Backend
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000 --host 0.0.0.0
```

### Frontend
```bash
cd frontend
npm install
npx expo start
```

### Documentación de la API
Disponible en `http://localhost:8000/docs` (Swagger UI)

## 📊 Datasets utilizados

- `data/rutas.json` — 15 rutas con 8 posiciones GPS cada una
- `data/colonias-rutas.json` — mapeo colonia → ruta + horario estimado  
- `data/notificaciones.json` — 3 eventos de notificación push

## 👤 Equipo

- **hack_21031301_c761d3** — HackOnLinces 2026