Election API

I built this project to practice backend development using a real world use case - a government election system. It covers voter registration, candidate management, vote casting, results computation and data visualization.

What I used

• Python and FastAPI for the REST API
• MySQL for the database with 17 related tables
• SQLAlchemy as the ORM
• Pandas for cleaning and loading CSV data into the database
• NumPy for vote statistics and majority threshold calculations
• Matplotlib and Seaborn for generating election charts
• JWT and bcrypt for voter authentication
• Docker to containerize the whole thing

How to run it

Clone the repo and create a .env file from the example:

cp .env.example .env

Update the .env with your MySQL credentials then either run with Docker:

docker compose up --build

Or run locally after installing dependencies:

pip install -r requirements.txt
uvicorn app.main:app --reload

The API will be available at http://localhost:8000 and the interactive docs at http://localhost:8000/docs

Seeding the database

To load sample data run:

python3 scripts/seed.py

This uses Pandas to clean the CSV files, validate the data and load everything into MySQL. It also flags duplicate registrations and saves rejected records to the reports folder.

What the API covers

The system handles voters, candidates, parties, regions, constituencies and embassies. Voters can register, login and cast votes for president, governor, senator and member of parliament. Each vote is validated against the voter's region and constituency.

There is also support for special voters including blind voters who need braille ballots, deaf voters, physically disabled, elderly, sick, pregnant and diaspora voters casting from embassies abroad.

Election staff including inspectors, vote collectors, helpers and tallying stations are managed through admin protected endpoints.

Results endpoints compute vote share, wasted votes and government majority status. There are 12 chart endpoints that return PNG images generated with Matplotlib and Seaborn.

Default admin

After running the seed script you can login with admin@election.com and the password set in your .env file under ADMIN_PASSWORD.