Plataforma de coordinación de ayuda material y logística en emergencias. Conecta a ciudadanía, organizaciones y coordinación durante una catástrofe: publica los puntos logísticos verificados, recoge y valida necesidades, casa ofertas de material con quien las pide, organiza voluntariado y partes de campo, y mantiene todo en un mapa en tiempo real — minimizando el ruido y los desplazamientos inútiles.
Producto de la organización Global Emergency. Multi-emergencia, multilingüe (ES/EN), con privacidad por diseño.
| Dominio | Capacidades |
|---|---|
| Emergencias | Multi-emergencia con estados (activa / en pausa), kill-switch (corta altas cuando no está activa), comunicado oficial, plantillas (p. ej. "Emergencia sanitaria") y lista de "qué NO llevar ahora". |
| Puntos logísticos | Ficha del punto (almacén/transporte…), rol origen→intermedio→destino (incl. destinatario final como receptor del recurso destino), inventario declarado (qué material/insumos tiene cada lugar: nombre, cantidad, unidad, categoría y presentación), nivel de confianza (verificado / oficial vía acreditación), semáforo de estado (operativo/saturado/en pausa/cerrado) y autoservicio del responsable. |
| Necesidades | Ciclo crear→validar→público, categorías (incl. sanitarias: medicamentos, equipos, insumos, personal), prioridad, ítems con cantidad, caducidad/frescura (48 h, "verifica antes de actuar"), y personal sanitario ↔ matching con el roster de voluntarios. |
| Ofertas de material | Oferta general o dirigida a una necesidad concreta + matching oferta↔necesidad desde coordinación. |
| Logística / Transporte | Capacidades de transporte ofrecidas por transportistas (ventanas, ruta, volumen) + expediciones (shipments) con ciclo de estado y sugerencia de capacidades para cubrirlas desde coordinación. |
| Voluntariado | Roster con skills / disponibilidad / vehículo + tareas con asignación y check-in/out. |
| Partes de campo | Partes de campo (incidencia/stock/estado) con fotos, prioridad y punto logístico relacionado; cola de revisión en coordinación. |
| Mapa | Leaflet con capas (puntos, necesidades), clustering de marcadores, carga por viewport (bounding-box) (/in-bounds), búsqueda server-side (?q=, pg_trgm), proximidad geo ("puntos cerca de ti", /nearby) y privacidad de ubicación (coordenadas aproximadas para entidades sensibles, "tu ubicación no se publica"). |
| Acceso / Autorización | Roles/permisos/grants con jerarquía de scopes, delegación con atenuación, grupos/cuadrillas con managers, API keys para integraciones automáticas y consola de administración (UI admin/manager/user). |
| Plataforma | Identidad JWT + OAuth (Google/Facebook), acreditación de organizaciones, notificaciones in-app, auditoría de acciones, métricas, geocodificación (Nominatim), almacenamiento de ficheros, i18n ES/EN, PWA (manifest + service worker + autoguardado de borradores), API pública de solo-lectura con portal /docs para desarrolladores y seguridad (Helmet, rate-limit, CORS). |
Monorepo pnpm con arquitectura hexagonal / DDD (puertos y adaptadores, bounded contexts) en el backend y Atomic Design en el frontend.
ResponseGrid/
├─ apps/
│ ├─ api/ NestJS 11 · hexagonal/DDD · Drizzle ORM · Postgres + Redis (BullMQ)
│ └─ web/ Next.js 16 · React 19 · App Router · Tailwind · Leaflet · PWA
├─ packages/
│ └─ api-client/ Cliente TypeScript tipado (openapi-fetch) generado desde la API
└─ docs/ Especificaciones, fichas de feature y planes
18 bounded contexts en apps/api/src/contexts/: emergencies, resources, needs, offers, supplies, logistics, volunteers, reports, identity, groups, organizations, accreditation, templates, notifications, audit, metrics, geocoding, files. La autorización (grants, service-accounts, API keys) vive en identity y las cuadrillas en groups. El dominio de insumos (supplies) es la fuente única del modelo de línea de material —Category (enum canónico de categorías), CategoryDefinition (tabla categories: etiquetas/jerarquía/alias) y el value object SupplyLine (nombre/cantidad/unidad/categoría/presentación)— reutilizado por needs, offers, resources (inventario por lugar) y logistics.
Stack: NestJS 11 · Next.js 16 · React 19 · TypeScript · Drizzle ORM · PostgreSQL 16 · Redis 7 (BullMQ) · Tailwind · Leaflet · Jest · ESLint + Prettier.
Requisitos: Node ≥ 20, pnpm, Docker.
# 1) Dependencias
pnpm install
# 2) Postgres (5433) + Redis (6380)
docker compose up -d
# 3) Variables de entorno
cp apps/api/.env.example apps/api/.env # rellena JWT_SECRET y, si usas login social, las claves OAuth
cp apps/web/.env.example apps/web/.env.local
# 4) Migraciones (aplícalas a la BD de dev)
# drizzle-kit puede colgarse en Windows/Git Bash → se aplican con psql:
for f in apps/api/drizzle/*.sql; do docker exec -i $(docker compose ps -q postgres) psql -U reliefhub -d reliefhub < "$f"; done
# 5) Datos de demo
pnpm --filter api exec ts-node scripts/seed-identity.ts
pnpm --filter api exec ts-node scripts/seed-emergencies.ts
pnpm --filter api exec ts-node scripts/seed-templates.ts
# 6) Arrancar
pnpm --filter api start:dev # API en http://localhost:3000 (Swagger en /docs)
pnpm --filter web dev # Web en http://localhost:3001Credenciales demo (solo si DEMO_MODE=true en apps/web/.env.local): coord@reliefhub.org / coord1234.
Tras tocar endpoints de la API:
pnpm gen:apiregenera el cliente tipado (packages/api-client/src/schema.ts).
pnpm --filter api test # unitarios + integración (jest --runInBand)
pnpm --filter api test:e2e # end-to-end (requiere Postgres/Redis)
pnpm --filter api lint # ESLint
pnpm --filter web lint
pnpm --filter web build
pnpm --filter api build # nest build — gate de CIDesarrollo guiado por TDD; Clean Code, SOLID y DDD en el backend, Atomic Design en el frontend.
Implementado y verificado: ciclo de vida de emergencia + kill-switch, confianza/acreditación, semáforo de puntos, voluntariado + tareas, partes de campo + fotos, plantillas, notificaciones, auditoría, PWA, i18n, métricas; categorías sanitarias, caducidad de necesidades, privacidad de ubicación, matching personal↔voluntarios; autorización completa (roles/permisos/grants/grupos/cuadrillas/API keys); dominio de insumos unificado (SupplyLine + Category compartidos por necesidades, ofertas, inventario y logística; tabla categories/CategoryDefinition con etiquetas y jerarquía; GET /categories); inventario declarado por lugar (qué material tiene cada punto, capturado en /registrar); operativo escalable (taxonomía como datos, recursos enriquecidos con accepts/contact/schedule/manager/provenance, paginación/filtros/facets, clustering, fichas ricas); búsqueda server-side (?q=, pg_trgm); proximidad geo (/nearby + UX "puntos cerca de ti"); mapa por bounding-box (/in-bounds); API pública + portal /docs para desarrolladores; destinatarios finales (rol en recurso destino); rebranding Global Emergency (marca, footer, páginas SEO, icono).
Backlog (en GitHub Issues): necesidades nominales por beneficiario, oferta como compromiso de entrega, rutas/isócronas (la cercanía puntual ya está), cola offline real, directorio de servicios gratuitos, CTA de emergencia nacional, agrupado y stock vivo (palés/cajas/lotes sobre SupplyLine, movimientos de inventario, reconciliación stock↔necesidades e indicadores de impacto — el inventario declarado por lugar y las capacidades/expediciones de transporte ya están), catálogo maestro de insumos (Supply referenciado por id → dedupe y matching), ingesta multi-fuente (enchufar fuentes externas como acopiove/REDH).
Consulta AGENTS.md como guía canónica de convenciones, bounded contexts y patrones del proyecto.
Flujo de trabajo:
- Crea una rama desde
main(feat/,fix/,docs/, …). - Abre un PR con
Closes #NNen la descripción. - Asegúrate de que CI pase: format → lint →
pnpm --filter api build(nest build) → test. - Squash-merge cuando el PR esté aprobado y verde.
No se hace push directo a main (branch protection activa).
docs/deploy/aws-free-tier.md— guía paso a paso: web en Vercel + API/Postgres/Redis en una EC2 + S3 (la guía usa t3.micro free-tier; producción corre en t3.small por el agente de observabilidad). Artefactos endeploy/(Dockerfile,docker-compose.prod.yml, migraciones, Caddy).deploy/datadog.md— observabilidad: agente Datadog (host, contenedores, Postgres+DBM, Redis, logs y APM/trazas), sitio EU.
ARCHITECTURE.md— guía corta de arquitectura para nuevos colaboradores.- GitHub Issues — backlog y tracking de features/bugs (EPICs + sub-issues, labels, plantillas).
docs/features/queda como specs legacy congeladas (referencia histórica; ver su00-indice.md). 01-especificacion-producto-y-arquitectura.mdyespecificacion_plataforma_ayuda_solidaria.md— especificación de producto y arquitectura.