Sistema de Inventario para la ONG La Gran Familia
FullstackReactSupabaseSocial ImpactTypeScriptPostgreSQL

Sistema de Inventario para la ONG La Gran Familia

Deployment Date
Repository

Sistema de Inventario para la ONG La Gran Familia

Resumen Ejecutivo

Este proyecto de impacto social corresponde al desarrollo de una solución full-stack de gestión de inventario y trazabilidad de donaciones concebida para la ONG “La Gran Familia”. Creado en colaboración por Bry Ramírez y Carlos A. Rasgo, el sistema centraliza la administración de bienes donados, fechas de expiración de alimentos/insumos, almacenes múltiples y la red de donantes mediante una Single Page Application en React 18 y un backend serverless en Supabase respaldado por PostgreSQL.

Situación

La organización benéfica “La Gran Familia” manejaba su flujo de donaciones e inventario mediante registros manuales en papel e insumos sin catalogar. Esta falta de digitalización provocaba pérdida de productos perecederos por fecha de vencimiento no detectada a tiempo, incapacidad para certificar la recepción de ayudas a los donantes y falta de transparencia en la distribución hacia las comunidades beneficiarias.

Objetivo

  1. Diseñar e implementar una arquitectura limpia (Clean Architecture) para el control de inventario en tiempo real.
  2. Garantizar la integridad transaccional atómica al registrar donaciones masivas y lotes con fechas de vencimiento.
  3. Asegurar la privacidad de la información y el control de acceso por roles (RBAC) mediante políticas de Row Level Security (RLS) en la base de datos PostgreSQL.

Arquitectura y Desarrollo

El sistema adopta patrones de arquitectura limpia con estricta separación de capas (Dominio, Datos, Presentación):

1. Frontend SPA (React 18 + TypeScript + Vite)

  • Gestión de Estado de Servidor: Integración de TanStack React Query para caché automático, invalidación de consultas en segundo plano y actualización optimista de la UI.
  • Rendimiento de Renderizado: Virtualización de listas mediante React Window para la visualización fluida de miles de registros de donaciones sin degradar el navegador.
  • Validación y Formularios: Esquemas estrictos de validación con Zod, exportación de reportes a Excel con ExcelJS y componentes responsivos en Tailwind CSS.

2. Backend Serverless (Supabase & PostgreSQL)

  • Modelo Relacional de 9 Entidades: Productos, Lotes de Stock, Donaciones, Items de Donación, Donantes, Almacenes, Categorías, Marcas y Usuarios.
  • Integridad Transaccional Atómica: Creación de funciones almacenadas SQL como create_donation_atomic para procesar el ingreso de donaciones complejas en una única transacción atómica sin condiciones de carrera.
  • Políticas de Seguridad (Row Level Security): Configuración de directivas RLS en PostgreSQL que restringen la visibilidad y modificación de datos según el rol asignado al usuario (Administrador, Operador, Consultor).

Módulos Especiales / Features Destacadas

1. Alerta Temprana de Expiración de Lotes

Un módulo automatizado que analiza las fechas de vencimiento de productos perecederos y clasifica el inventario en un semáforo visual (Verde: > 60 días, Amarillo: 15-60 días, Rojo: < 15 días), priorizando la salida de insumos próximos a vencer.

2. Trazabilidad y Certificación a Donantes

Genera reportes estadísticos exportables que consolidan el volumen histórico aportado por cada donante institucional o individual y su destino de entrega.

Ciclo de Vida de una Donación

  1. Recepción: El operador registra la donación asociando el donante, almacén de destino y productos con sus lotes/fechas.
  2. Procesamiento Atómico: create_donation_atomic inserta la cabecera y detalle de la donación, actualizando existencias.
  3. Control de Calidad: El sistema califica la vigencia de los insumos y emite alertas de vencimiento.
  4. Despacho: Distribución autorizada conforme a las políticas de seguridad RLS por rol.

Stack Tecnológico Completo

Capa Tecnologías
Frontend UI React 18, TypeScript, Vite, Tailwind CSS
Data Query & Forms TanStack React Query, Zod, React Window, Recharts, ExcelJS
Backend & DB Supabase Serverless, PostgreSQL, PL/pgSQL, Row Level Security (RLS)
Testing & CI/CD Vitest, Testing Library, Vercel

Resultados y Logros

  • Cobertura Operativa: Plataforma completa con más de 8 módulos funcionales para el control de inventario de impacto social.
  • Seguridad Garantizada: Políticas RLS que previenen accesos no autorizados a datos de donantes y operaciones.
  • Aprendizaje y Aporte: Demostración práctica de desarrollo colaborativo de software con utilidad social directa.