# datosbolivia/elecciones2025 architecture

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

- Interactive diagram: https://gitdiagram.com/datosbolivia/elecciones2025
- Repository: https://github.com/datosbolivia/elecciones2025

## Overview

##### Project type and purpose
- Type: A data-driven, static site project. It ingests raw geographic and historical election data, runs ETL scripts to produce JSON/GeoJSON outputs, and publishes a client-side visualization (built with ObservableHQ/Node.js).
- Purpose: Provide up-to-date and historical election results for Bolivia (2025), combining geo-data, tabular results, and interactive charts/maps.

##### File structure
- Top-level directories
- .github/workflows: CI/CD pipelines to “actualizar” (update) data and “publicar” (publish) the site
- geo: raw geographic packages (.gpkg) for 2020 & 2025 plus a Jupyter notebook (geoelectoral.ipynb)
- resultados/datos: Python ETL scripts (actualizar.py, preparar.py) plus subfolders holding CSVs, GeoJSON, and a consolidated resultados.json
- resultados/vista: front-end code (Node.js + ObservableHQ config) with markdown, images, and package.json
- resultados_historicos: Parquet files for elections from 1979–2020 and a Jupyter atlas notebook
- Patterns & considerations
- ETL pipeline implemented in Python
- Static-site generation / Single-Page-App for visualization
- CI/CD driven by GitHub Actions

##### README
- Confirms: “Elecciones generales 2025 en Bolivia”
- No in-depth architecture, so rely on structure to infer pipeline phases.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Raw Data Layer
    subgraph "Raw Data Layer"
        direction TB
        RawDataGeo["Geographic Data (geo/)"]:::data
        RawDataHist["Historical Election Data (resultados_historicos/)"]:::data
    end

    %% ETL Pipeline
    subgraph "ETL Pipeline" 
        direction TB
        Refresh["Data Refresh Script\n(actualizar.py)"]:::processing
        Prepare["Data Preparation Script\n(preparar.py)"]:::processing
        GeoNotebook["Geo Analysis Notebook\n(geoelectoral.ipynb)"]:::processing
        HistNotebook["Historical Analysis Notebook\n(atlas_electoral.ipynb)"]:::processing
    end

    %% Data Output / Storage
    subgraph "Data Storage Outputs"
        direction TB
        ResultsJSON["Consolidated Results JSON\n(resultados.json)"]:::output
        GeoJSON["Precincts GeoJSON\n(recintos.geojson)"]:::output
        CSVs["Tabular CSV Outputs\n(especiales/, presidente/, uninominales/)"]:::output
    end

    %% Visualization Front-End
    subgraph "Visualization Front-End"
        direction TB
        ConfigPkg["Project Config\n(package.json)"]:::frontend
        ConfigObs["ObservableHQ Config\n(observablehq.config.js)"]:::frontend
        SrcAssets["Source Files & Assets\n(src/)"]:::frontend
        Build["Build Process (Node.js)"]:::frontend
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        direction TB
        CI_ETL["ETL Workflow\n(.github/workflows/actualizar.yml)"]:::cicd
        CI_Deploy["Deployment Workflow\n(.github/workflows/publicar.yml)"]:::cicd
    end

    %% Deployed Site and Users
    Deployed["Deployed Static Site"]:::frontend
    User["Web Browser Users"]:::user

    %% Data Flow Arrows
    RawDataGeo -->|"ingest"| Refresh
    RawDataHist -->|"ingest"| Refresh
    Refresh -->|"transform"| Prepare
    RawDataGeo --> GeoNotebook
    RawDataHist --> HistNotebook
    Prepare --> ResultsJSON
    Prepare --> GeoJSON
    Prepare --> CSVs
    ResultsJSON -->|"build input"| Build
    GeoJSON -->|"build input"| Build
    CSVs -->|"build input"| Build
    Build -->|"deploy"| Deployed
    Deployed -->|"consume"| User

    %% CI/CD Arrows
    CI_ETL -->|"triggers"| Refresh
    CI_ETL -->|"triggers"| Prepare
    CI_Deploy -->|"triggers"| Build
    CI_Deploy -->|"deploys"| Deployed

    %% Click Events
    click RawDataGeo "https://github.com/datosbolivia/elecciones2025/tree/main/geo/"
    click RawDataHist "https://github.com/datosbolivia/elecciones2025/tree/main/resultados_historicos/"
    click Refresh "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/datos/actualizar.py"
    click Prepare "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/datos/preparar.py"
    click GeoNotebook "https://github.com/datosbolivia/elecciones2025/blob/main/geo/geoelectoral.ipynb"
    click HistNotebook "https://github.com/datosbolivia/elecciones2025/blob/main/resultados_historicos/atlas_electoral.ipynb"
    click ResultsJSON "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/datos/resultados.json"
    click GeoJSON "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/datos/recintos.geojson"
    click CSVs "https://github.com/datosbolivia/elecciones2025/tree/main/resultados/datos/"
    click ConfigPkg "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/vista/package.json"
    click ConfigObs "https://github.com/datosbolivia/elecciones2025/blob/main/resultados/vista/observablehq.config.js"
    click SrcAssets "https://github.com/datosbolivia/elecciones2025/tree/main/resultados/vista/src/"
    click CI_ETL "https://github.com/datosbolivia/elecciones2025/blob/main/.github/workflows/actualizar.yml"
    click CI_Deploy "https://github.com/datosbolivia/elecciones2025/blob/main/.github/workflows/publicar.yml"

    %% Styles
    classDef data fill:#cce5ff,stroke:#66b0ff,color:#003366
    classDef processing fill:#d4edda,stroke:#81c784,color:#1b5e20
    classDef output fill:#e2e3e5,stroke:#bcbdbf,color:#343a40
    classDef frontend fill:#fff3cd,stroke:#ffecb5,color:#856404
    classDef cicd fill:#f3e5f5,stroke:#ce93d8,color:#4a148c
    classDef user fill:#f8f9fa,stroke:#6c757d,color:#495057
```
