HackOnLinces-2026 — Sistema de Notificación Inteligente de Recolección de Residuos

Equipo: Acapulquitos Boys
Problemática: App móvil de notificación privada de ETA del camión de basura + guía de separación de residuos
Stack: Flutter 3.44 + Python FastAPI + SQLite + WebSocket

📚 Índice de la Wiki

🏗️ Arquitectura

Visión general del sistema — diagrama de módulos y flujos de datos
Arquitectura del backend — Clean Architecture en FastAPI
Arquitectura del frontend — Feature-first con Riverpod

🚀 Setup y ejecución

Requisitos previos — Flutter, Python, Git, FVM
Configurar el backend (Módulo B) — instalar dependencias, correr servidor
Configurar Flutter (Módulos C y D) — integrar módulos, correr app
Variables de entorno — configuración de .env para desarrollo

🔌 Contratos de API

Endpoints REST — GET /eta, POST /alerts/breakdown, etc.
WebSocket — protocolo de eventos en tiempo real
Modelos de datos — JSON schemas de request/response
Integración entre módulos — cómo Persona A, B, C, D se conectan

🔧 Troubleshooting

Errores comunes — CORS, WebSocket, pub get fails
Problemas de versiones — Dart SDK, Java, dependencias
Debug del simulador — verificar estado del camión

🎯 Quick Start (5 minutos)

Backend (Persona B)

cd basura_backend
pip install -r requirements.txt
uvicorn app.main:app --reload
# Servidor corriendo en http://localhost:8000

Frontend (Persona C + D)

cd basura_app
fvm use 3.44.0              # o 3.22.0 si bajaron versión
fvm flutter pub get
fvm flutter run

Demo completo

Arranca backend → POST /admin/route/RUTA-01/start
Abre Flutter → navega a /guia (módulo D) o home (módulo C)
WebSocket conecta automáticamente → recibes notificaciones cada 10s

👥 División de trabajo

Persona	Módulo	Responsabilidad
A	Backend Auth	JWT, RBAC, alta de domicilios, validación de zona
B	Backend Simulador	Ruta, ETA, WebSocket, notificaciones push
C	Flutter UI principal	Login, home ETA, WebSocket, Riverpod
D	Flutter Guía offline	Separación de residuos, búsqueda, tema compartido

📦 Estructura del repo

hackathon-acapulquitos-boys/
├── basura_backend/          # Módulo B — Python FastAPI
│   ├── app/
│   │   ├── domain/          # Entidades, interfaces
│   │   ├── data/            # Repositories, datasources
│   │   ├── services/        # Simulador, WebSocket Manager
│   │   ├── use_cases/       # Lógica de negocio
│   │   └── api/routes/      # Endpoints REST
│   └── requirements.txt
│
├── basura_app/              # Flutter (Módulos C + D integrados)
│   ├── lib/
│   │   ├── core/theme/      # AppTheme compartido (Persona D)
│   │   └── features/
│   │       ├── auth/        # Login (Persona C)
│   │       ├── eta/         # Home + WebSocket (Persona C)
│   │       └── recycling_guide/  # Guía offline (Persona D)
│   ├── assets/
│   │   └── recycling_guide.json  # 4 categorías de residuos
│   └── pubspec.yaml
│
└── docs/                    # Esta wiki

🔐 Reglas de Git

Branches: feature/<nombre>, bugfix/<nombre>
PR a dev cuando algo funcione (compila sin errores)
Commit cada 30 min — evita perder trabajo
Reunión rápida cada 2 hrs — sincronizar progreso

📞 Contacto y soporte

Si algo falla:

Revisa Errores comunes
Verifica Versiones
Pregunta en el chat del equipo

¡Éxito en el hackathon! 🚀