# jpacoch/cartovote architecture

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

- Interactive diagram: https://gitdiagram.com/jpacoch/cartovote
- Repository: https://github.com/jpacoch/cartovote

## Overview

##### What this project is (type + purpose)
**CartoVote** is a **lightweight, static, browser-based frontend** for a **municipal geo-questionnaire**. The user experience is: open the web page → interact with a **Leaflet** map → answer questions → drop one or more pins to add geographic context → persist/submit results to a **Supabase** backend (DB + API).

Given the file tree, this repo is essentially a **client-side web app** (no server code in-repo) that likely calls Supabase directly from the browser.

##### What the file structure implies architecturally
From the tree:

- `index.html`
Entry point, page layout, and script/style inclusion. Often where Leaflet is initialized (or where the container for the map exists).

- `css/style.css`

- `js/script.js`
The entire “application layer” is likely in here:
- Initialization (Leaflet)
- survey UI logic / state
- pin placement + coordinate capture
- request(s) to Supabase (insert rows, store responses, etc.)

- `package.json`

What’s **not** present is equally important:
- No `backend/`, no `server/`, no API implementation in-repo → backend is **external** (Supabase).

##### README-derived architecture signals
The README explicitly states:
- **Leaflet.js** is the mapping engine (external library used in-browser).
- **Supabase** is the database (and implicitly, the API/auth layer if used).
- Pure HTML/CSS/Vanilla JS.

- **Client-side app**
- **Map tile/provider dependencies** (Leaflet typically requires a tile server such as OpenStreetMap or another provider—Leaflet itself is just the rendering/interaction library)
- **Supabase** as the persistence and (potentially) auth layer

##### Browser / Frontend Web App
- `index.html` (UI shell)
- `css/style.css` (presentation)
- `js/script.js` (app logic)
- Leaflet.js (client library dependency)
##### Map Tile Service (external)
- e.g., OpenStreetMap tiles or another provider (even if not named in README, it’s a real runtime dependency in most Leaflet setups)
##### Supabase (external backend)
- Supabase REST/GraphQL (PostgREST) and/or JS client calls (whatever the JS uses)
- **Database (Postgres)** storing survey responses, pin coordinates, timestamps, question answers, etc.
- (Optional if used) Supabase Auth / Storage

##### Page load
- User → Browser: navigate to URL
- Browser → Static Hosting: GET `index.html`, `style.css`, `script.js`

##### Map rendering
- Browser (Leaflet) → Tile Service: GET map tiles (XYZ tile requests)

##### Survey + pin capture
- User → Browser: clicks map / drops pin / answers questions
- Browser: stores state locally (in-memory; optionally localStorage—only show if code does it)

##### Persist submission
- Browser → Supabase API: insert/update survey response + geometry (lat/lng)
- Supabase API → Postgres: write rows
- Supabase API → Browser: success/failure response

If authentication exists (not in README), only add it if `script.js` demonstrates it. Otherwise, keep it out to avoid inaccuracy.

##### Architectural patterns/design principles that fit this repo
- **Client-heavy architecture** (logic runs in-browser)
- **Backend-as-a-Service (BaaS)** via Supabase
- **Externalized mapping infrastructure** (tile provider + Leaflet)

##### Relevant technologies prominently
- “Vanilla JS (ES6) + Leaflet.js”
- “Supabase (Postgres + API)”
- “Map Tile Provider (e.g., OSM)”
- “Static Hosting (serves HTML/CSS/JS)”

- User
- Static Hosting (serves the site)
- Browser App (CartoVote)
- Tile Provider
- Supabase (API + DB)

- User → Hosting (load app)
- Browser ↔ Tile Provider (tiles)
- Browser ↔ Supabase (submit/retrieve)

- UI Layer (survey form, buttons)
- Module (Leaflet initialization, pin drop, geometry capture)
- State Model (responses in memory)
- Data Access Layer (Supabase client / fetch calls)

- UI ↔ State
- Module ↔ State
- Data Access ↔ Supabase

- Developer machine (npm install, static assets)
- CI/CD (if any—only add if README/package.json indicates)
- Hosting/CDN
- Supabase project (env vars/keys)
Where configuration lives (e.g., Supabase URL/key in JS—if true in code).

##### What “very detailed” means here (without overthinking)
For this project, “detailed” is mainly about:
- separating **static hosting** vs **in-browser runtime**
- separating **Leaflet library** vs **tile provider**
- separating **Supabase API** vs **Supabase DB**
- explicitly showing **data flows** for: load → interact → submit

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context (C4-L1)
  %% =========================
  U["User (Citizen)"]:::external

  subgraph "Internet / External Services"
    H["Static Hosting / CDN"]:::hosting
    TP["Map Tile Service (e.g., OpenStreetMap tiles)"]:::external
    subgraph "Supabase (BaaS)"
      SA["Supabase API (PostgREST/HTTP)"]:::api
      SDB[("Supabase Postgres (DB)")]:::db
    end
  end

  subgraph "Client Runtime"
    B["Web Browser"]:::runtime

    subgraph "CartoVote Frontend (Static Web App)"
      IDX["index.html (UI shell)"]:::inrepo
      CSS["style.css (presentation)"]:::inrepo
      JS["script.js (application logic)"]:::inrepo
      CSSDIR["css/ (directory)"]:::inrepo
      JSDIR["js/ (directory)"]:::inrepo

      subgraph "Logical modules (within script.js)"
        UI["Survey UI Layer (form/buttons)"]:::module
        MAP["Map Module (Leaflet init + pin drop)"]:::module
        STATE["State Model (in-memory responses + pins)"]:::module
        DAL["Data Access Layer (Supabase client / fetch)"]:::module
        LF["Leaflet.js (client library)"]:::external
      end
    end
  end

  %% Context flows (vertical, explicit)
  U -->|"navigate_to_URL"| H
  H -->|"HTTP_GET_static_assets"| B

  B -->|"load_index_html"| IDX
  B -->|"load_css"| CSS
  B -->|"load_js"| JS

  %% In-app interactions
  U -->|"answer_questions"| UI
  U -->|"drop_pins_on_map"| MAP

  IDX -->|"renders_layout"| UI
  CSS -->|"styles_UI"| UI
  JS -->|"bootstraps_app"| UI
  JS -->|"bootstraps_app"| MAP

  UI <-->|"read_write"| STATE
  MAP <-->|"read_write"| STATE
  MAP -->|"uses"| LF

  %% External runtime dependencies
  MAP -->|"XYZ_tile_requests"| TP

  DAL -->|"insert_update_responses_and_points"| SA
  SA -->|"write_rows"| SDB
  SA -->|"success_failure"| DAL

  %% Optional: submission trigger path
  UI -->|"submit"| DAL
  STATE -->|"payload"| DAL

  %% =========================
  %% Dev/Tooling (separate lane)
  %% =========================
  subgraph "Development / Tooling (non-runtime)"
    DEV["Developer Machine"]:::tooling
    NPM["npm (deps/scripts)"]:::tooling
    DOC["README (project notes)"]:::doc
  end

  DEV -->|"npm_install_run"| NPM
  NPM -->|"produces_static_payload"| H
  DOC -->|"documents_leaflet_and_supabase_usage"| DEV

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click IDX "https://github.com/jpacoch/cartovote/blob/main/index.html"
  click CSS "https://github.com/jpacoch/cartovote/blob/main/css/style.css"
  click JS "https://github.com/jpacoch/cartovote/blob/main/js/script.js"
  click DOC "https://github.com/jpacoch/cartovote/blob/main/README.md"
  click NPM "https://github.com/jpacoch/cartovote/blob/main/package.json"

  %% Directory click events
  click CSSDIR "https://github.com/jpacoch/cartovote/tree/main/css/"
  click JSDIR "https://github.com/jpacoch/cartovote/tree/main/js/"

  %% =========================
  %% Styles (color coding)
  %% =========================
  classDef inrepo fill:#cfe8ff,stroke:#2563eb,stroke-width:1.5px,color:#0b1b33
  classDef module fill:#e6f2ff,stroke:#1d4ed8,stroke-width:1px,color:#0b1b33
  classDef external fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#111827
  classDef hosting fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1f1300
  classDef api fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#05210e
  classDef db fill:#bbf7d0,stroke:#15803d,stroke-width:1.5px,color:#05210e
  classDef runtime fill:#ede9fe,stroke:#6d28d9,stroke-width:1.5px,color:#1a1033
  classDef tooling fill:#fff7ed,stroke:#c2410c,stroke-width:1px,color:#1f1300
  classDef doc fill:#fef9c3,stroke:#ca8a04,stroke-width:1px,color:#1f1300
```
