Home
Backend del sistema de gestión para centros de acopio y reciclaje — multi-tenant, Spring Boot 4 + Java 21.
RecyOps es un monolito modular multi-tenant: cada empresa cliente vive en su propio esquema de PostgreSQL dentro de un único proyecto Supabase, con autenticación JWT (Supabase Auth, ES256) y autorización por rol (ADMIN / OPERARIO / SUPERADMIN). Esta wiki documenta cómo está construido, por qué se tomaron las decisiones que se tomaron, y qué mirar primero si algo se rompe.
| Si necesitas... | Ve a |
|---|---|
| Entender la arquitectura de punta a punta (filtros, multi-tenant, seguridad) | Arquitectura |
| Ver qué hace cada módulo del API, sus endpoints y su flujo de negocio | Módulos (índice abajo) |
| Saber por qué se tomó una decisión técnica concreta | Decisiones de arquitectura (ADR) (índice abajo) |
| Resolver una duda operativa (observabilidad, esquema de datos, testing) | Documentación temática (índice abajo) |
Dos diagramas Mermaid por módulo: flujo de negocio end-to-end y secuencia HTTP del endpoint más relevante. Generados leyendo el código directamente (controllers, services, entities, SecurityConfig), no por inferencia.
| Módulo | Rol requerido | Qué hace |
|---|---|---|
| Auth | público | Login/refresh/recuperación — delegado 100% a Supabase Auth |
| Plataforma | SUPERADMIN |
Provisión de nuevas empresas (tenants) |
| Tenant | — (infra) | Resolución de esquema por request, migraciones Flyway |
| Usuario | ADMIN |
Alta/edición/bloqueo de trabajadores, sincronizado con Supabase |
| Bodega |
ADMIN (lectura: cualquiera) |
Catálogo de bodegas/almacenes |
| Material |
ADMIN (lectura: cualquiera) |
Catálogo de materiales reciclables |
| Proveedor | ADMIN |
Catálogo de proveedores + calificación |
| Ingreso | autenticado | Pesaje/registro de material que trae un cliente — no toca inventario |
| Entrega | ADMIN |
Recepción de proveedor con flujo de estados — único módulo que mueve inventario |
| Convenio | ADMIN |
Contratos de compra/venta/intercambio/servicio — no toca inventario |
| Inventario | ADMIN |
Ledger de stock por bodega, ajustes, mermas, bloqueo optimista |
| Tarea | autenticado (fino en service) | Tareas asignadas a trabajadores, con avances |
| Dashboard | autenticado | Agregados de lectura cruzando 5 módulos |
| Log | ADMIN |
Lectura de logs (general/transacciones/errores) |
| ADR | Decisión |
|---|---|
| ADR-001 | Flyway para las migraciones multi-tenant (un historial por esquema) |
| ADR-002 | Endurecimiento de seguridad y confiabilidad (rate limiting, timeouts, bloqueo optimista) |
| Doc | Tema |
|---|---|
| Multi-tenant y esquema Supabase | Cómo se aísla cada empresa a nivel de base de datos |
| Observabilidad: Grafana + Prometheus | Qué métricas vigilar y por qué, dado el diseño multi-tenant |
| Testing y coverage | Suites unitarias (service + controller), JaCoCo, gaps conocidos |
| Bodies de prueba (Bruno) | JSON de ejemplo para probar cada endpoint manualmente |
| Integrar un servicio en Python | Guía de referencia para comunicar otro lenguaje con este backend |
| Postmortem: creación de materiales | Diagnóstico y fix de un bug real de julio 2026 (ya corregido) |
./mvnw spring-boot:run # levantar la app
./mvnw test # tests unitarios (rápido, sin Docker)
./mvnw verify # + tests de integración (Testcontainers, necesita Docker)
cd monitoreo && docker compose up -d # Prometheus (:9090) + Grafana (:3000, admin/recyops)Detalle completo de setup y convenciones de código en el CLAUDE.md del repo.