e-Vote: An Offline-First, Electronic Voting System for Academic and Institutional Elections

e-Vote is a modern, secure, and resilient digital voting platform designed for academic and institutional elections. The system aims to provide a trustworthy, accessible, and offline-capable voting experience while maintaining transparency, integrity, and ease of administration.

🛠️ Tech Stack

The project is built with a modern full-stack architecture focused on reliability and scalability:

• Next.js 16 with the App Router
• React 19 and TypeScript
• Clerk for authentication and secure access control
• Supabase for PostgreSQL database, real-time data handling, and Row Level Security
• CSS Modules for polished, component-based UI styling
• Mermaid for flow and system documentation

🎯 Problem We Are Solving

Traditional voting processes in academic institutions often face several challenges:

• Manual or paper-based voting is slow, error-prone, and difficult to audit
• Limited access to secure digital participation for students and staff
• Vulnerability to duplicate voting, tampering, and inconsistent record keeping
• Poor resilience in environments where internet connectivity may be unreliable

💡 Solution

e-Vote addresses these issues by providing a digital election platform that is:

• Secure and authenticated through institutional identity management
• Designed to support fair, verifiable voting processes
• Structured for offline-friendly operation and future synchronization workflows
• Easy to manage for administrators, candidates, and voters

✨ Key Features

• Secure voter authentication and role-based access
• Election and candidate management for administrators
• Student-facing dashboard for active and upcoming elections
• Vote verification and receipt support
• Offline-ready architecture for resilient institutional deployments
• Audit-friendly data structure for review and accountability

📁 File Structure

src/
  app/
    admin/
    auditor/
    candidate/
    dashboard/
    ec/
    election/
    voter/
    api/
    sign-in/
    sign-up/
  components/
  lib/
public/
  assets/

🔄 How It Works

The workflow below illustrates the core flow of the e-Vote system:

flowchart TD
    A[User Accesses Platform] --> B[Authentication via Clerk]
    B --> C[Dashboard / Election View]
    C --> D{Offline or Online?}
    D -->|Online| E[Cast Vote Securely]
    D -->|Offline| F[Queue Vote for Sync]
    E --> G[Store Vote Record in Supabase]
    F --> G
    G --> H[Admin Review and Election Monitoring]
    H --> I[Results and Verification]

Loading

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

• Node.js
• npm

Installation

git clone <your-repository-url>
cd e-Vote
npm install

Environment Variables

Create a .env.local file in the root directory and configure the following values:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key
CLERK_WEBHOOK_SECRET=your_webhook_secret

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Run the Development Server

npm run dev

Open http://localhost:3000 in your browser to view the application.

🧱 Database and System Design

The application uses a relational data model centered around election management and secure vote recording. Core entities include:

• Voters
• Elections
• Candidates
• Votes
• Admin and institutional roles

This design supports integrity, role-based access, and future expansion for more advanced electoral processes.

Election banners and candidate images

For an existing Supabase project, run supabase/election-media-setup.sql in the Supabase SQL Editor. It configures the public election-media bucket, adds the election banner, reviewer feedback, and timezone columns, and converts existing election wall-clock timestamps once from the previous UTC interpretation to Africa/Kampala. New election form times are entered in Kampala time and stored as UTC instants. Image uploads accept JPG, PNG, WebP, and AVIF files up to 4 MB and use SUPABASE_SERVICE_ROLE_KEY on the server.

For persisted in-app notifications, run supabase/notifications.sql in the Supabase SQL Editor. The notification API and RLS policies scope records to the signed-in Clerk user; election, candidate-review, and ballot events create notifications automatically.

Do not rerun supabase/schema.sql against a database with live data: that bootstrap file contains DROP TABLE statements. The election media setup script is the additive update for existing installations.

📌 Project Purpose

This project is developed as a Capstone Project focused on practical innovation in digital governance, secure systems, and user-centered design for institutional use.

👏 Project Credits

Project Hail Mary

Developers:

• EGABO AARON
• NATOZO PATIENCE MARTHA
• NIWASIIMA ASHELYCOLE

Supervised by:

• MR. KUMAKECH MICHAEL

---

Built with purpose, integrity, and a vision for modern digital elections.