docs: README completo con arquitectura y stack

README.md

@@ -1 +1,84 @@
-# HackOnLinces 2026 - Sistema de Notificación de Recolección de Residuos
+# 🚛 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
+- [ ] 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