4.1 KiB
Alternativas de implementación
Este documento registra las decisiones técnicas tomadas y por qué. El criterio guía es mínimo coste de mantenimiento para una organización sin ánimo de lucro, siguiendo KISS y evitando YAGNI.
1. Framework frontend
| Opción | Pros | Contras |
|---|---|---|
| React + Vite (elegido) | Ecosistema enorme, fácil encontrar contribuidores, build rápido. | Requiere build step. |
| Next.js | SSR, rutas, imágenes. | Demasiado para una SPA de una página; aumenta complejidad y coste de hosting. |
| Vanilla JS | Sin dependencias. | Más código manual, menos contribuidores familiarizados. |
Decisión: React + Vite. Es el stack más común y los contribuidores potenciales lo conocen. Vite mantiene la configuración mínima.
2. Mapa
| Opción | Pros | Contras |
|---|---|---|
| Leaflet + OpenStreetMap (elegido) | Open source, sin claves API, sin coste, tiles gratuitos. | Menos pulido que Mapbox. |
| Mapbox GL | Más bonito, mejor rendimiento. | Requiere API key y tiene cuotas de pago. |
| Google Maps | Familiar. | Requiere facturación activada, cuotas estrictas, no encaja con espíritu open source. |
Decisión: Leaflet con tiles de OpenStreetMap. Cero coste, sin claves, y la
librería react-leaflet lo hace trivial de integrar.
3. Backend y almacenamiento de datos
| Opción | Pros | Contras |
|---|---|---|
| Backend-as-a-Service (Supabase o similar) elegido | Sin servidor que mantener, base de datos gestionada, panel de moderación incluido en su dashboard. Plan gratuito generoso. | Dependencia de un proveedor. |
| Backend propio (Node + Postgres) | Control total. | Hay que mantenerlo, pagarlo, securizarlo. Alto coste para una ONG. |
| Archivo JSON en el repositorio | Sin backend, máxima simplicidad. | Las contribuciones tendrían que llegar como Pull Requests, fricción alta para no-técnicos. |
Decisión: BaaS tipo Supabase. Para el prototipo, la capa de datos se
abstrae en src/services/businessRepository.js, así que cambiar de proveedor
después es localizado. El prototipo entregado usa un mock en memoria para
no acoplar a un proveedor concreto antes de que la organización lo decida.
4. Moderación
| Opción | Pros | Contras |
|---|---|---|
| Aprobación desde el dashboard del BaaS (elegido) | Cero código extra. El revisor cambia un campo status de pending a approved. |
Requiere acceso al dashboard. |
| Panel de moderación dentro de la app | Más cómodo. | Requiere autenticación, roles, vistas extra: explosión de complejidad. |
Decisión: La moderación vive fuera del frontend público. El modelo de
datos incluye un campo status (pending / approved / rejected). El
frontend solo lee los approved.
5. Estilos
| Opción | Pros | Contras |
|---|---|---|
| CSS plano con variables (elegido) | Cero dependencias, fácil de leer, los contribuidores con HTML/CSS básico pueden colaborar. | Sin utilidades. |
| Tailwind | Productivo. | Cadena de build extra, curva de aprendizaje. |
| CSS-in-JS | Componentes encapsulados. | Runtime extra, peor accesibilidad para nuevos contribuidores. |
Decisión: CSS plano. La app es de una página; no se justifica más.
6. Gestión de estado
Decisión: useState y useEffect de React. No hay Redux, Zustand ni
Context global. La app es pequeña; añadir una librería de estado sería YAGNI.
7. Geocodificación de direcciones del formulario
Decisión para el prototipo: el usuario hace clic en el mapa para fijar la ubicación, o introduce lat/lng. Geocodificación automática vía Nominatim (OpenStreetMap) queda como mejora futura con bajo coste de añadir.
8. Tests
Decisión: el prototipo no incluye suite de tests para no inflarlo, pero la estructura (servicios separados de componentes, funciones puras donde posible) facilita añadirlos. Cuando se incorporen, Vitest es la elección natural por integrarse con Vite sin configuración.
9. Despliegue
Decisión recomendada: GitHub Pages o Cloudflare Pages (gratuitos
para open source). Una SPA estática construida con vite build se despliega
sin coste y sin servidor. Ver docs/06-github-setup.md.