# victorclaros0/obraspublicas architecture

> Architecture diagram of the GitHub repository victorclaros0/obraspublicas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victorclaros0/obraspublicas
- Repository: https://github.com/victorclaros0/obraspublicas

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actors
    %% =========================
    AdminUser["Admin User\n(crea obras en /admin)"]:::actor
    ViewerUser["Viewer User\n(escanea QR y ve /obra/:id)"]:::actor

    %% =========================
    %% Hosting (optional)
    %% =========================
    subgraph "Static Hosting (optional)"
        Hosting["Static Hosting\n(serve index.html + bundle)"]:::external
    end

    %% =========================
    %% Browser / Runtime
    %% =========================
    subgraph "User & Browser Runtime"
        Browser["Browser (Web Runtime)"]:::external

        subgraph "Browser APIs"
            Geo["Geolocation API"]:::external
        end
    end

    %% =========================
    %% SPA (React + Vite)
    %% =========================
    subgraph "RutaFix SPA (React + Vite + TS)"
        Bootstrap["Bootstrap\n(index.html + main.tsx)"]:::spa
        AppShell["App Shell\n(App.tsx + styles)"]:::spa

        subgraph "Router / Pages"
            Pages["Pages Index\n(src/pages/*)"]:::spa
            Home["Home Page\n(/)"]:::spa
            Admin["Admin Page\n(/admin)\ncreate obra + QR"]:::spa
            ObraView["Obra Public View\n(/obra/:id)\nread obra + map + route"]:::spa
        end

        subgraph "Map & UI Components"
            LeafletUI["Map UI\n(Leaflet + react-leaflet)"]:::spa
            RoutingControl["RoutingControl\n(Leaflet Routing Machine wrapper)"]:::spa
            QR["QR Renderer\n(qrcode.react)"]:::spa
        end

        subgraph "Integrations (src/lib/*)"
            SupabaseClient["Supabase Client\n(supabase-js)"]:::integration
            ORSClient["OpenRouteService Client\n(optional; fallback straight line)"]:::integration
            Env["Environment Config\n(VITE_*)"]:::config
        end

        Fallback["Fallback Routing\n(straight line between waypoints)"]:::optional
    end

    %% =========================
    %% Supabase (BaaS)
    %% =========================
    subgraph "Supabase (BaaS)"
        SupabaseAPI["Supabase Data API\n(PostgREST / HTTP)"]:::supabase
        AuthRLS["Auth + RLS Policies"]:::supabase
        DB[("Postgres DB\nTable: obras")]:::db
        SchemaRLS["DB Schema + Policies\n(obras.sql)"]:::supabase
    end

    %% =========================
    %% External APIs
    %% =========================
    subgraph "External APIs"
        ORS["OpenRouteService API\n(optional)"]:::external
    end

    %% =========================
    %% Top-down access
    %% =========================
    AdminUser -->|"uses"| Browser
    ViewerUser -->|"uses"| Browser
    Browser -->|"loads"| Hosting
    Hosting -->|"serves SPA assets"| Bootstrap

    %% SPA wiring
    Bootstrap -->|"mounts"| AppShell
    AppShell -->|"routes"| Pages
    Pages -->|"route /"| Home
    Pages -->|"route /admin"| Admin
    Pages -->|"route /obra/:id"| ObraView

    %% Map composition
    Admin -->|"renders"| LeafletUI
    ObraView -->|"renders"| LeafletUI
    LeafletUI -->|"uses"| RoutingControl

    %% Geolocation for viewer route origin
    ObraView -->|"GetCurrentPosition()"| Geo
    Geo -->|"current location"| ObraView

    %% CRUD flows to Supabase
    Admin -->|"INSERT obra"| SupabaseClient
    ObraView -->|"SELECT obra by id"| SupabaseClient
    SupabaseClient -->|"HTTP requests"| SupabaseAPI
    SupabaseAPI -->|"enforces"| AuthRLS
    AuthRLS -->|"applies policies"| DB
    SupabaseAPI -->|"read/write"| DB

    %% DB schema/policies source
    SchemaRLS -->|"defines DDL + RLS"| DB
    SchemaRLS -->|"defines policies"| AuthRLS

    %% QR flow
    Admin -->|"generate QR (encodes URL /obra/:id)"| QR
    QR -->|"scan -> open /obra/:id"| ViewerUser

    %% Routing flows (optional ORS)
    ObraView -->|"Request route"| ORSClient
    ORSClient -->|"HTTP route request"| ORS
    ORS -->|"Return route geometry"| ORSClient
    ORSClient -->|"route geometry"| RoutingControl

    %% Fallback behavior (no ORS key)
    ORSClient -.->|"if no API key"| Fallback
    Fallback -.->|"straight line geometry"| RoutingControl

    %% Env vars feeding integrations
    Env -->|"VITE_SUPABASE_URL\nVITE_SUPABASE_ANON_KEY"| SupabaseClient
    Env -->|"VITE_OPENROUTESERVICE_KEY (optional)"| ORSClient

    %% =========================
    %% Click events (from component mapping)
    %% =========================
    click Bootstrap "https://github.com/victorclaros0/obraspublicas/blob/main/src/main.tsx"
    click Bootstrap "https://github.com/victorclaros0/obraspublicas/blob/main/index.html"
    click Bootstrap "https://github.com/victorclaros0/obraspublicas/blob/main/vite.config.ts"

    click AppShell "https://github.com/victorclaros0/obraspublicas/blob/main/src/App.tsx"
    click AppShell "https://github.com/victorclaros0/obraspublicas/blob/main/src/App.css"
    click AppShell "https://github.com/victorclaros0/obraspublicas/blob/main/src/index.css"

    click Pages "https://github.com/victorclaros0/obraspublicas/tree/main/src/pages/"
    click Home "https://github.com/victorclaros0/obraspublicas/blob/main/src/pages/Home.tsx"
    click Admin "https://github.com/victorclaros0/obraspublicas/blob/main/src/pages/Admin.tsx"
    click ObraView "https://github.com/victorclaros0/obraspublicas/blob/main/src/pages/ObraView.tsx"

    click RoutingControl "https://github.com/victorclaros0/obraspublicas/blob/main/src/components/RoutingControl.tsx"
    click SupabaseClient "https://github.com/victorclaros0/obraspublicas/blob/main/src/lib/supabase.ts"
    click ORSClient "https://github.com/victorclaros0/obraspublicas/blob/main/src/lib/openrouteservice.ts"

    click SchemaRLS "https://github.com/victorclaros0/obraspublicas/blob/main/supabase/obras.sql"
    click Env "https://github.com/victorclaros0/obraspublicas/blob/main/.env.example"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827
    classDef spa fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b3a
    classDef integration fill:#bfdbfe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b3a
    classDef config fill:#e0e7ff,stroke:#3730a3,stroke-width:1.5px,color:#111827
    classDef supabase fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#052e16
    classDef db fill:#bbf7d0,stroke:#16a34a,stroke-width:2px,color:#052e16
    classDef external fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef optional fill:#f3e8ff,stroke:#7c3aed,stroke-width:1.5px,stroke-dasharray:6 4,color:#2e1065
```
