# peterargueta/csv2map architecture

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

- Interactive diagram: https://gitdiagram.com/peterargueta/csv2map
- Repository: https://github.com/peterargueta/csv2map

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“CSV2MAP GT”) whose goal is to let users upload CSV files containing Guatemalan department codes, preview the selected departments on an interactive map, and download corresponding geospatial files (`.shp` and `.kml`) packaged in a ZIP.

##### File Structure Analysis
- Top level
- `main.py` (FastAPI app)
- `requirements.txt` (Python deps)
- `Departamentos/` (base shapefile assets: `.shp`, `.dbf`, etc.)
- `utils/normalizar_csv.py` (CSV‐to‐Geo preparation)
- Frontend (`geo_guate_frontend/`)
- `public/Departamentos/departamentos.geojson` (static GeoJSON)
- `src/` (React components: `MapaDepartamentos.jsx`, `UploadForm.jsx`, `App.jsx`)
- Vite/Tailwind config
- Deployment/config: `.npmrc`, `vite.config.js`, `postcss.config.js`, etc.

##### README Insights
- Frontend: React + Vite + Tailwind CSS + Leaflet.js
- Backend: FastAPI + GeoPandas
- Hosting: Vercel (frontend), Render (API)
- No relational database—geospatial data served from static shapefiles or on-the-fly generation.

##### Main Components (to include
A. Client Browser (React SPA)
- Components: UploadForm, MapaDepartamentos
- Leaflet.js to render GeoJSON layers
B. Frontend Server (Vercel)
- Serves static React build and public assets (including base GeoJSON)
C. REST API Service (Render)
- FastAPI app (`main.py`) with endpoints:
- `/upload` accepts CSV, returns map data & ZIP download URL
- `/download` streams generated ZIP
D. Data Processing Layer
- `utils/normalizar_csv.py` normalizes CSV → GeoDataFrame
- GeoPandas reads `Departamentos/*.shp` and filters by codes
- Generates `.shp` and `.kml`, packages into ZIP
E. Storage/Filesystem
- Base shapefiles (`Departamentos/`)
- Temporary output (in-memory or temp folder for ZIP)
F. External Services
- Vercel (frontend hosting)
- Render.com (API hosting)
- Google Analytics (tracking on frontend)

##### Relationships & Data Flows
1) User interacts with React SPA → selects CSV file
2) SPA (browser) sends POST `/upload` → FastAPI
3) FastAPI calls `normalizar_csv`, loads shapefile, filters, writes `.shp`/`.kml`, zips
4) FastAPI returns:
- GeoJSON payload for immediate map rendering
- URL or stream to download ZIP
5) SPA displays GeoJSON via Leaflet
6) User clicks “Download” → SPA fetches ZIP from `/download` endpoint
7) Analytics events sent to Google Analytics

##### Architectural Patterns & Principles
- Clear separation of concerns: UI layer (React) vs. API/data layer (FastAPI)
- Stateless API calls; no persistent DB
- Reuse of base geospatial assets (shapefiles)
- Temporary data generation on demand
- Single-page application (SPA) communicating with RESTful endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser and Analytics
    subgraph "User Environment"
        BROWSER["Client Browser"]:::frontend
        GA["Google Analytics"]:::external
    end

    %% Vercel Hosting and Frontend Code
    subgraph "Vercel Hosting"
        CDN["Vercel CDN\n(Static React Assets)"]:::external

        subgraph "Frontend Code"
            Main["main.jsx"]:::frontend
            App["App.jsx"]:::frontend
            Upload["UploadForm.jsx"]:::frontend
            MapC["MapaDepartamentos.jsx"]:::frontend
            GeoJSON["departamentos.geojson"]:::frontend
        end

        subgraph "Frontend Config"
            Pkg["package.json"]:::frontend
            Postcss["postcss.config.js"]:::frontend
            ViteCfg["vite.config.js"]:::frontend
            Tailwind["tailwind.config.js"]:::frontend
            Npmrc[".npmrc"]:::frontend
        end
    end

    %% Render Hosting and API/Data Processing
    subgraph "Render Hosting"
        API["FastAPI Service"]:::api

        subgraph "API Code"
            MainPy["main.py"]:::api
            MainDbg["main_debug.py"]:::api
            Req["requirements.txt"]:::api
        end

        subgraph "Data Processing"
            Norm["normalizar_csv.py"]:::data
        end
    end

    %% Storage / Filesystem
    subgraph "Storage"
        FS["Filesystem"]:::storage
        subgraph "Base Shapefiles"
            Shp["departamentos.shp"]:::storage
            Dbf["departamentos.dbf"]:::storage
            Prj["departamentos.prj"]:::storage
            Shx["departamentos.shx"]:::storage
            Cpg["departamentos.cpg"]:::storage
            Qmd["departamentos.qmd"]:::storage
        end
    end

    %% Repository Configuration
    subgraph "Repository Config"
        Gitignore[".gitignore"]:::external
        Readme["README.md"]:::external
    end

    %% Connections: Frontend load and analytics
    CDN -->|"Serves SPA"| BROWSER
    BROWSER -->|"Loads React SPA"| CDN
    BROWSER -->|"Sends Analytics"| GA
    BROWSER -->|"Sends Analytics"| GA

    %% Frontend internal relations
    Main --> App
    App --> Upload
    App --> MapC
    CDN --> GeoJSON
    MapC --> GeoJSON

    %% Frontend config relation
    Pkg --> CDN
    Postcss --> CDN
    ViteCfg --> CDN
    Tailwind --> CDN
    Npmrc --> CDN

    %% API calls from browser
    BROWSER -->|POST /upload| API
    BROWSER -->|GET /download| API

    %% API to Data Processing and Storage
    MainPy --> Norm
    API --> Norm
    API -->|"Reads/Writes Shapefiles"| FS
    Norm --> FS

    %% Storage internals
    FS --> Shp
    FS --> Dbf
    FS --> Prj
    FS --> Shx
    FS --> Cpg
    FS --> Qmd

    %% Repository config relation
    Gitignore --> MainPy
    Readme --> MainPy

    %% Click Events
    click Main "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/src/main.jsx"
    click App "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/src/App.jsx"
    click Upload "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/src/components/UploadForm.jsx"
    click MapC "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/src/components/MapaDepartamentos.jsx"
    click GeoJSON "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/public/Departamentos/departamentos.geojson"
    click Pkg "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/package.json"
    click Postcss "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/postcss.config.js"
    click ViteCfg "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/vite.config.js"
    click Tailwind "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/tailwind.config.js"
    click Npmrc "https://github.com/peterargueta/csv2map/blob/main/geo_guate_frontend/.npmrc"
    click MainPy "https://github.com/peterargueta/csv2map/blob/main/main.py"
    click MainDbg "https://github.com/peterargueta/csv2map/blob/main/main_debug.py"
    click Req "https://github.com/peterargueta/csv2map/blob/main/requirements.txt"
    click Norm "https://github.com/peterargueta/csv2map/blob/main/utils/normalizar_csv.py"
    click Shp "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.shp"
    click Dbf "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.dbf"
    click Prj "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.prj"
    click Shx "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.shx"
    click Cpg "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.cpg"
    click Qmd "https://github.com/peterargueta/csv2map/blob/main/Departamentos/departamentos.qmd"
    click Gitignore "https://github.com/peterargueta/csv2map/blob/main/.gitignore"
    click Readme "https://github.com/peterargueta/csv2map/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#E0F8E0,stroke:#28A745,color:#28A745;
    classDef data fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef storage fill:#FFF0F5,stroke:#C71585,color:#C71585;
    classDef external fill:#F0F0F0,stroke:#6A5A5A,color:#6A5A5A;
```
