How victorclaros0/obraspublicas works
Tipo y propósito del proyecto (qué estás diagramando)
RutaFix es una SPA frontend (React + Vite + TS) que usa Supabase como backend (BaaS) para persistencia y lectura de “obras viales” y que integra mapas/ruteo (Leaflet + Leaflet Routing Machine) y QR para compartir enlaces a una vista pública.
En términos de arquitectura, el “sistema” real no es solo el repo: es Browser App + Supabase (DB + API + Auth/RLS) + OpenRouteService (opcional), todo orquestado desde el cliente.
Lectura del file tree (pistas estructurales)
Componentes/zonas claras del repo:
• App Vite/React
• index.html, vite.config.ts, src/main.tsx (bootstrap)
• src/App.tsx, src/App.css, src/index.css
• Páginas (rutas)
• src/pages/Home.tsx
• src/pages/Admin.tsx
• src/pages/ObraView.tsx
• Componentes UI/Mapa
• src/components/RoutingControl.tsx (punto clave: encapsula Leaflet Routing Machine)
• Integraciones externas / “clientes”
• src/lib/supabase.ts (cliente Supabase)
• src/lib/openrouteservice.ts (cliente ORS; fallback a línea recta si no hay key)
• Infra/DB
• supabase/obras.sql (DDL + RLS/policies)
• Config y build
• .env.example (VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_OPENROUTESERVICE_KEY)
• tailwind.config.js, postcss.config.js, eslint.config.js, tsconfig*
Esto sugiere un diagrama con (1) runtime en browser, (2) servicios externos, (3) almacenamiento/DB y (4) flujos por página (Admin vs ObraView).
Lo más importante del README (qué flujos dibujar)
Rutas funcionales del sistema:
• /admin: usuario coloca 2 puntos (obra y desvío) + metadata → guarda en Supabase → genera QR con URL /obra/:id
• /obra/:id: carga obra desde Supabase → muestra mapa con marcador rojo (obra) y ruta hacia desvío:
• ruteo: Leaflet Routing Machine; opcionalmente “rutas reales” via OpenRouteService
• además: usa ubicación del usuario (Geolocation en browser) para origen de ruta
Entidades principales:
• Obra en tabla obras: id, título, descripción, coords obra/desvío, fotos[], created_at
• RLS/policies (en Supabase) condicionan acceso (aunque sea “demo”, es un componente de arquitectura)
Cómo dibujar el diagrama de arquitectura “más exacto” para este proyecto
Te recomiendo 2 niveles (ambos en el mismo lienzo o en 2 slides):
Diagrama C4 – Contenedores (macro)
Dibuja estos contenedores como cajas separadas:
User (Admin / Viewer)
• Actor humano (quien crea obras) y actor público (quien escanea QR).
Browser / SPA: RutaFix (React + Vite build)
• Subcomponentes internos (sub-cajas o labels):
• Router / Pages: Home, Admin, ObraView
• UI: Leaflet + react-leaflet
• Routing: RoutingControl.tsx (Leaflet Routing Machine)
• QR rendering: qrcode.react
• Integrations: supabase.ts, openrouteservice.ts
Supabase (BaaS)
• Sub-cajas:
• Postgres DB (tabla obras)
• REST/HTTP API (PostgREST) o “Supabase Data API”
• Auth/RLS (políticas de acceso; aunque uses anon key, RLS gobierna)
OpenRouteService API (opcional)
• Caja externa. Nota: “si no hay API key, fallback: línea recta”.
(Opcional) Hosting/Static assets
• Si lo quieres completo: “Static hosting (Vercel/Netlify/etc)” sirviendo index.html + bundle.
• No está en el repo, pero en un diagrama de sistema suele ser útil.
Relaciones (flechas) clave:
• User → Browser SPA (interacciones UI)
• Browser SPA → Supabase (CRUD sobre obras)
• Browser SPA → OpenRouteService (request de ruta/segmentos)
• Browser SPA → Browser Geolocation API (para “mi ubicación” en /obra/:id)
• (Opcional) QR: Browser SPA → “QR contains URL” → User scans → Browser opens /obra/:id
Diagrama de secuencia / data-flow por caso de uso (micro)
Haz 2 mini-secuencias, porque el sistema tiene dos flujos dominantes:
Admin submits form → SPA llama a Supabase
• INSERT obras(...) (vía supabase-js)
SPA calcula ruta
• Preferente: SPA → OpenRouteService (con key) → devuelve geometría/steps
• Alternativo: routing “simple” (línea recta entre waypoints) si no hay key
Patrones/decisiones arquitectónicas a resaltar (para que el diagrama sea “fiel”)
• Backendless / BaaS-centric: no hay servidor propio; la lógica de aplicación vive en el cliente.
• Rutas = páginas: src/pages/* mapea directo a rutas del README (/, /admin, /obra/:id).
• **Integraciones encapsuladas en src/lib/***: buen punto para dibujar “adaptadores” a servicios externos.
• Degradación funcional (fallback): sin ORS key, el sistema sigue operando con ruteo simplificado.
• Seguridad y acceso: “anon key” + RLS (policies en supabase/obras.sql) es parte del diseño, no un detalle.
Elementos que debe incluir el diagrama (checklist concreto)
Para este repo, si quieres “separar en tantos componentes como sea posible” sin inventar:
Componentes (cajas) mínimas
• React SPA
• Router (pages)
• Admin page
• ObraView page
• Leaflet Map
• RoutingControl (Leaflet Routing Machine)
• Supabase client (supabase.ts)
• OpenRouteService client (openrouteservice.ts)
• QR component
• Supabase
• API layer
• Postgres (tabla obras)
• RLS/Policies
• OpenRouteService API (externo)
• Browser APIs
• Geolocation
Flechas (con etiquetas)
• “INSERT obra”
• “SELECT obra by id”
• “Request route”
• “Return route geometry”
• “Get current location”
• “QR encodes URL /obra/:id”
Convenciones visuales
• Colores:
• Azul: componentes SPA (código en src/)
• Verde: Supabase (managed backend)
• Morado/Gris: servicios externos (OpenRouteService, Browser APIs)
• Formas:
• Rectángulos: contenedores/componentes
• Cilindro: DB Postgres
• Nube: servicios externos
• Bordes:
• Línea discontinua para “opcional” (OpenRouteService y el fallback)
• Notas:
• Anotar .env variables cerca de integraciones:
• VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY
• VITE_OPENROUTESERVICE_KEY (opcional)
Título: “RutaFix – Arquitectura (SPA + Supabase + Routing)”
External APIs
Dentro de “SPA (React)” coloca las páginas y libs; dentro de “Supabase” coloca API/DB/RLS; en “External APIs” coloca ORS + Geolocation.
Validación rápida: ¿tu diagrama quedó “correcto”?
• ¿Se entiende que Admin crea y Viewer consume (dos actores, dos flujos)?
• ¿Se ve explícitamente que Supabase es el backend (DB + policies) y que el cliente habla directo con él?
• ¿OpenRouteService aparece como opcional y con fallback?
• ¿/obra/:id depende de (a) lectura DB + (b) geolocalización + (c) ruteo?
Si todas son “sí”, estás representando el sistema con alta fidelidad al repo y al README.