Electoral Data Analytics Platform

A full-stack platform for tracking live Peruvian election results from ONPE (Oficina Nacional de Procesos Electorales) during the 2026 general elections. The system continuously ingests official vote count data, stores time-series snapshots, runs probabilistic outcome simulations, and serves an interactive web dashboard with an AI-powered chat assistant.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        ONPE API                             │
│         (Peru's official electoral authority)               │
└──────────────────────┬──────────────────────────────────────┘
                       │ Selenium + httpx (requires browser session)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Backend (Python 3.12 / FastAPI)                            │
│                                                             │
│  fetcher.py ──► processor.py ──► storage.py (JSON files)    │
│                                      │                      │
│                              ┌───────┴───────┐              │
│                              ▼               ▼              │
│                       predictor.py      AI/rag.py           │
│                    (Monte Carlo)    (vectorstore rebuild)   │
│                                                             │
│  scheduler.py (60 s polling, change detection)              │
│  main.py (FastAPI routes, SSE streaming)                    │
└──────────────────────┬──────────────────────────────────────┘
                       │ REST / SSE
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Frontend (React 19 / TypeScript / Vite)                    │
│                                                             │
│  Dashboard  │  Electoral Map  │  Predictions  │  Timeline   │
│  Candidates │  History        │  AI Chat      │  Actas      │
└─────────────────────────────────────────────────────────────┘

---

Repository Structure

.
├── Backend/            # Python FastAPI data pipeline and API server
│   ├── main.py
│   ├── fetcher.py
│   ├── processor.py
│   ├── scheduler.py
│   ├── storage.py
│   ├── predictor.py
│   ├── config.py
│   ├── actas_controller.py
│   ├── AI/
│   │   ├── rag.py
│   │   ├── data_loader.py
│   │   ├── embeddings.py
│   │   └── vectorstore.py
│   ├── ImageRecognition/   # Bulk acta PDF downloader
│   ├── requirements.txt
│   └── README.md
├── Frontend/           # React + TypeScript dashboard
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── types/
│   ├── public/
│   │   └── peru-departamentos.geojson
│   ├── package.json
│   └── README.md
└── Dockerfile          # Multi-stage build: Node → Alpine Python + Nginx

---

How It Works

Data Ingestion

The ONPE API requires an active browser session. fetcher.py manages a headless Chromium instance via Selenium to establish sessions, then uses httpx for HTTP requests. Retry logic with exponential backoff handles transient API failures.

ETL & Transformation

processor.py normalizes raw API responses: it unifies field names across election types, computes participation rates and vote share percentages, ranks candidates, and assembles complete snapshot objects with a consistent schema regardless of election type.

Storage & Change Detection

storage.py writes to a structured data/ directory. The scheduler only persists a new snapshot when the counted-ballots percentage increases by more than 0.1%, avoiding storage of redundant updates. Atomic writes (temp file → rename) prevent consumers from reading partial data.

Statistical Modeling

predictor.py runs 100,000 Monte Carlo simulations using a Dirichlet-Multinomial model vectorized with NumPy. Rather than drawing independent Gaussian noise per candidate (which can produce vote shares that don't sum correctly), the simulator draws each run's full vote-share vector from a Dirichlet distribution whose concentration parameter κ is derived from cross-regional variance and historical volatility. This enforces compositional consistency across candidates while still capturing momentum and geographic uncertainty. The output is a probability distribution over finishing positions, confidence intervals (p5–p95), and overtake probabilities between adjacent-ranked candidates.

AI Chat (RAG)

The AI/ module implements a retrieval-augmented generation pipeline:

1. data_loader.py converts the latest snapshots into labeled text chunks.
2. embeddings.py encodes them locally using sentence-transformers (all-MiniLM-L6-v2) — no external service required.
3. vectorstore.py stores embeddings in memory and ranks by cosine similarity.
4. rag.py retrieves the top-k relevant chunks plus a set of always-pinned sources, and injects them into the LLM context window so responses stay grounded in current data.
5. main.py streams the final response token-by-token via Groq (llama-3.3-70b-versatile) using Server-Sent Events.

---

Available Elections

Key	Election
presidential	National presidential race
senate_national	Senate — National Electoral District
senate_regional	Senate — Regional Electoral Districts
deputies	Congressional Deputies
parlamento_andino	Andean Parliament

---

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite, Tailwind CSS 4, Recharts, D3-geo
Backend	Python 3.12, FastAPI, Uvicorn, Selenium, httpx
AI / NLP	Groq API (LLM streaming), sentence-transformers (local embeddings), custom RAG pipeline
Deployment	Docker, Nginx, multi-stage build

---

Running Locally

Prerequisites

• Node.js 20+
• Python 3.12+
• Google Chrome or Chromium installed
• A free Groq API key for the AI chat

Backend

cd Backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env           # add GROQ_API_KEY to enable AI chat
uvicorn main:app --reload --port 8000

Frontend

cd Frontend
npm install
cp .env.example .env.local
npm run dev                    # http://localhost:5173

The Vite dev server proxies /api/* requests to http://localhost:8000.

Docker (full stack)

docker build -t onpe-platform .
docker run -p 5000:5000 onpe-platform