# saisantoshv3/electoral_bonds architecture

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

- Interactive diagram: https://gitdiagram.com/saisantoshv3/electoral_bonds
- Repository: https://github.com/saisantoshv3/electoral_bonds

## Overview

##### What this project is (type + purpose)
This repo is a **data-wrangling / dataset-building pipeline** (not a running service). Its purpose is to produce **donor- and recipient-wise “matched” electoral bond transactions** by linking two SBI/ECI datasets via **Electoral Bond Code**. The README explicitly mentions:
- PDFs as upstream source (ECI site; SBI-provided)
- **Tabula** used to extract CSVs from PDFs (manual/external step)
- **OpenRefine** used for clustering/deduping purchaser names (manual/external step)
- A Python script that likely performs the deterministic “matching” and outputs cleaned datasets

##### File tree analysis → components you must reflect
Top-level structure:

- `raw_files/`
- `encashed_parties.pdf`
- `purchased_companies.pdf`
These are the **raw upstream artifacts** (PDFs). They are *inputs* to the pipeline.

- `data/`
- `encashed.csv`
- `purchased.csv`
- `final.csv`
This is the **intermediate and final data products**. `encashed.csv` and `purchased.csv` are extracted/cleaned versions of the PDFs; `final.csv` is the matched dataset output.

- `script/`
- `electoral_bonds.py`

- `README.md`

##### data/purchased.csv → OpenRefine
- (Optionally also show `encashed.csv` being cleaned if applicable; README only explicitly mentions purchaser names.)
##### data/final.csv → End users

This is the core dataflow. Don’t invent APIs/databases—stay faithful to the repo.

##### Architectural pattern / design principle
Call it what it is:
- **Batch ETL / data pipeline**
- **Artifact-based workflow** (files as boundaries)
- **Deterministic matching** step (join by Electoral Bond Code)
- **Human-in-the-loop cleaning** (OpenRefine) is a first-class stage

- *Manual steps* vs *Automated steps*
- *Raw* vs *Intermediate* vs *Final* data

##### Relevant technologies
Explicitly label:
- Tabula (PDF → CSV)
- OpenRefine (data cleaning)
- Python script (`electoral_bonds.py`)
“Run locally / command-line execution” (since there’s no deployment structure indicated).

##### What NOT to include (to keep it accurate)
- Don’t imply OpenRefine/Tabula are Python dependencies; they’re external tools in the workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Title
  T["Electoral Bonds Matched Dataset Build Pipeline (Batch ETL + Human-in-the-loop)"]:::title

  %% =========================
  %% Sources / Upstream
  %% =========================
  subgraph "Sources (External + Raw Artifacts)"
    direction TB
    ECI["Election Commission of India (ECI) Website\n(PDF Source)"]:::external
    PDFP["Raw PDF: Purchased Companies"]:::raw
    PDFE["Raw PDF: Encashed Parties"]:::raw
  end

  %% =========================
  %% Manual / Semi-automated
  %% =========================
  subgraph "Manual / Semi-automated Steps (External Tools)"
    direction TB
    TAB["Tabula\n(PDF table extraction → CSV)"]:::manual
    OR["OpenRefine\n(Cluster/Deduplicate purchaser names)"]:::manual
  end

  %% =========================
  %% Data Artifacts
  %% =========================
  subgraph "Data Artifacts (Intermediate + Final)"
    direction TB
    CSVP["Intermediate CSV: purchased.csv\n(Normalized purchaser names after OpenRefine)"]:::data
    CSVE["Intermediate CSV: encashed.csv"]:::data
    FINAL["Final Output: final.csv\n(Matched dataset via Electoral Bond Code)"]:::final
  end

  %% =========================
  %% Automated Processing
  %% =========================
  subgraph "Automated Processing (Local Batch Job)"
    direction TB
    PY["Python ETL Script\n- Load purchased.csv + encashed.csv\n- Normalize keys (Bond Code, dates, amounts)\n- Join/match on Electoral Bond Code\n- Resolve duplicates/edge cases\n- Emit final.csv"]:::compute
  end

  %% =========================
  %% Downstream Consumers
  %% =========================
  subgraph "Consumers"
    direction TB
    USERS["Analysts / Journalists / Researchers"]:::consumer
  end

  %% =========================
  %% Documentation
  %% =========================
  DOC["Process Documentation\n(How to run + external tools)"]:::doc

  %% =========================
  %% Flow
  %% =========================
  T --> ECI

  ECI -->|"Download_PDFs_(manual)"| PDFP
  ECI -->|"Download_PDFs_(manual)"| PDFE

  PDFP -->|"Extract_tables"| TAB
  PDFE -->|"Extract_tables"| TAB

  TAB -->|"Export_CSV"| CSVP
  TAB -->|"Export_CSV"| CSVE

  CSVP -->|"Cluster_and_dedupe_names_(manual)"| OR
  OR -->|"Export_cleaned_CSV"| CSVP

  CSVP -->|"Batch_input"| PY
  CSVE -->|"Batch_input"| PY

  PY -->|"Match_join_on_Electoral_Bond_Code"| FINAL
  FINAL -->|"Publish_analyze"| USERS

  DOC -.->|"Documents_workflow_(Tabula/OpenRefine/Python)"| TAB
  DOC -.->|"Documents_workflow_(Tabula/OpenRefine/Python)"| OR
  DOC -.->|"Documents_script_usage"| PY

  %% =========================
  %% Click Events (mapped paths only)
  %% =========================
  click PDFE "https://github.com/saisantoshv3/electoral_bonds/blob/main/raw_files/encashed_parties.pdf"
  click PDFP "https://github.com/saisantoshv3/electoral_bonds/blob/main/raw_files/purchased_companies.pdf"
  click CSVE "https://github.com/saisantoshv3/electoral_bonds/blob/main/data/encashed.csv"
  click CSVP "https://github.com/saisantoshv3/electoral_bonds/blob/main/data/purchased.csv"
  click PY "https://github.com/saisantoshv3/electoral_bonds/blob/main/script/electoral_bonds.py"
  click FINAL "https://github.com/saisantoshv3/electoral_bonds/blob/main/data/final.csv"
  click DOC "https://github.com/saisantoshv3/electoral_bonds/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef title fill:#111827,stroke:#111827,color:#ffffff,stroke-width:1px
  classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
  classDef raw fill:#f3f4f6,stroke:#9ca3af,color:#111827,stroke-width:1px
  classDef manual fill:#fdba74,stroke:#c2410c,color:#111827,stroke-width:1px
  classDef compute fill:#93c5fd,stroke:#1d4ed8,color:#0b1220,stroke-width:1px
  classDef data fill:#c7d2fe,stroke:#4338ca,color:#0b1220,stroke-width:1px
  classDef final fill:#86efac,stroke:#166534,color:#052e16,stroke-width:1px
  classDef consumer fill:#fef08a,stroke:#a16207,color:#111827,stroke-width:1px
  classDef doc fill:#ddd6fe,stroke:#6d28d9,color:#111827,stroke-width:1px
```
