Skip to content

About

Election system built for our College of Computing Studies

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

JRMSU CCS Student Org Election System

Full-stack electronic voting platform built for the College of Computer Studies at Jose Rizal Memorial State University — designed to replace paper-based elections with a secure, real-time, mobile-first digital experience.

Student Voting Interface


Table of Contents


Overview

The JRMSU CCS Election System is a production-grade web application that digitizes the student organization election process. Students log in with their institutional credentials, cast votes across multiple positions, and receive an instant digital vote receipt — all from any device, no installation required.

Administrators get a real-time control panel to manage candidates, positions, student records, and election settings, with a live vote tally dashboard and printable reports.

Metric Value
Total Students Supported 638+
Positions Managed 28
Total Votes Cast (Live Election) 5,039
Voter Turnout Rate ~90%
Elected Officials Determined 35

Case Study

The Problem

The College of Computer Studies at JRMSU conducted student org elections using a manual, paper-based process. This caused:

  • Long queues and wasted class time during voting periods
  • Human counting errors and delayed results
  • No audit trail — votes could not be verified after counting
  • Accessibility issues — students had to be physically present to vote
  • Administrative overhead — manually tallying hundreds of ballots across multiple positions

The Solution

A web-based election platform that is:

  • Mobile-first — runs on any smartphone browser, no app install required
  • Secure — JWT authentication, bcrypt password hashing, server-side vote validation
  • Real-time — live vote counts update on the admin dashboard as votes come in
  • Auditable — every vote is stored with a timestamp and student ID in MongoDB
  • Tamper-resistant — students can only vote once per position; the backend enforces this independently of the frontend

The Outcome

The system was successfully deployed for the 2025–2026 school year election. Results were available instantly after the election period closed, compared to the previous multi-day manual counting process. Zero counting errors. Full voter receipt for every student.


Screenshots

Login & Authentication

Login Screen

Students sign in using their Student ID and last name. The system validates against the registered student database and issues a JWT token scoped to that session. Admins have a separate authenticated portal.


Admin Dashboard & Live Results

Admin Dashboard and Reports

The admin panel shows real-time stats: total enrolled students, votes cast, voter turnout progress bar, and a per-position leaderboard. The Reports tab shows elected officials ranked by vote count, filterable by course/program, with print support.


Student Voting Flow

Student Voting Flow

After login, students see their profile and election status. Voting is a guided step-by-step ballot — one position at a time — with a final review screen before submission. The system enforces eligibility rules per position (e.g., "4th Year Representatives" only appears for 4th-year students).


Vote Receipt, Reports & Settings

Vote Receipt and Settings

After submission, students receive a timestamped digital vote receipt. Admins can view the full elected officials list, export voter masterlists, and manage election settings (title, school year, open/close status, date range) — all without touching the database directly.


Technical Architecture

┌─────────────────────────────────────────────────┐
│                  Browser (Client)               │
│  React 18 + TypeScript + Tailwind CSS + Vite    │
│  Axios → /api proxy → Express backend           │
└──────────────────┬──────────────────────────────┘
                   │ HTTP / REST
                   ▼
┌─────────────────────────────────────────────────┐
│              Express.js API Server              │
│  JWT Auth Middleware → Route Handlers           │
│  bcryptjs · sharp (image compression)           │
│  Mongoose ODM → MongoDB Atlas                   │
└──────────────────┬──────────────────────────────┘
                   │ Mongoose / MongoDB Wire Protocol
                   ▼
┌─────────────────────────────────────────────────┐
│              MongoDB Atlas (Cloud)              │
│  Collections: students, candidates, positions,  │
│  votes, programs, admins, electionsettings      │
└─────────────────────────────────────────────────┘

Auth Flow

Student Login
  → POST /api/auth/login/student
  → bcrypt.compare(password, hash)
  → jwt.sign({ id, role: 'student' }, SECRET, { expiresIn: '12h' })
  → Token stored in localStorage
  → All subsequent requests: Authorization: Bearer <token>
  → Token verified on every protected route via auth middleware

Vote Submission Flow

Student clicks "Submit My Vote"
  → POST /api/votes/submit { votesMap: { positionId: [candidateId] } }
  → Server verifies JWT → loads student from DB
  → For each position: checks student hasn't already voted
  → Creates Vote documents (one per selection)
  → Increments candidate.vote_count atomically
  → Updates student.voted_positions + student.has_voted
  → Issues fresh JWT (updated has_voted state)
  → Returns updated student profile

Feature Breakdown

Student Portal

  • Secure login with Student ID + password (bcrypt-hashed)
  • Profile display: name, course, year level, student ID
  • Eligibility-aware ballot — positions filtered by course/year level/both
  • Step-by-step guided voting with progress indicator
  • Multi-candidate selection support (configurable per position)
  • Ballot review screen before final submission
  • Tamper-proof: each position voteable only once, enforced server-side
  • Timestamped vote receipt after submission

Admin Control Panel

  • Separate admin authentication (role-based JWT)
  • Real-time dashboard: student count, votes cast, turnout %, candidate leaderboard
  • Students Manager — server-side paginated table (20/page), search + filter by year/course/status, add/edit/delete
  • Candidates Manager — add candidates with photo upload (auto-compressed to ≤100KB via sharp), party color, description
  • Positions Manager — configurable voter eligibility per position (all / by course / by year / by course+year)
  • Programs Manager — manage available courses/programs
  • Reports — election results ranked by votes, voter masterlist (voted/not voted), print support
  • Settings — election title, school year, date range, open/close toggle

Infrastructure

  • Vite dev proxy /api → localhost:3001 (zero CORS issues in development)
  • Express serves built frontend in production (single process deployment)
  • Image compression pipeline: uploaded photos → sharp → JPEG ≤100KB → stored as base64
  • Seed script: node api/index.js --seed populates admin account + default programs + election settings
  • JWT persisted in localStorage, user object cached for instant page reload

Tech Stack

Layer Technology Purpose
Frontend Framework React 18 + TypeScript Component-based UI with full type safety
Build Tool Vite 7 Lightning-fast HMR dev server + production builds
Styling Tailwind CSS v4 Utility-first, mobile-first responsive design
HTTP Client Axios API calls with interceptors for auth + error handling
Backend Framework Express.js REST API routing, middleware pipeline
Database MongoDB Atlas + Mongoose Flexible document storage with schema validation
Authentication JSON Web Tokens (JWT) Stateless, role-aware session tokens
Password Security bcryptjs Salted password hashing (10 rounds)
Image Processing sharp Server-side image resize + JPEG compression
Icons Lucide React Consistent, lightweight icon set
Environment Replit + Node.js Cloud-hosted development and deployment

Engineering Highlights

Server-Side Pagination

Student records are fetched from MongoDB with .skip() + .limit() — not loaded all at once. Filters (search, year level, course, voted status) are applied as MongoDB query predicates, not in JavaScript. This means the system handles 10,000+ students with the same response time as 100.

Role-Based JWT Middleware

Every protected route runs through auth() → decodes the JWT → attaches req.user = { id, role }. Admin-only routes additionally run adminOnly(). Student-only routes run studentOnly(). No route can be accessed without the correct role, regardless of what the frontend sends.

Eligibility Engine

Position voter eligibility is evaluated server-side when building the ballot (GET /api/votes/ballot). The backend loads the student's course and year level, then filters active positions against their voter_eligibility config. The frontend never receives positions the student isn't eligible for.

Image Compression Pipeline

When an admin uploads a candidate photo, the raw base64 string is passed through a sharp pipeline that:

  1. Resizes to a max of 400×400px (preserving aspect ratio)
  2. Converts to JPEG
  3. Iteratively reduces quality (80 → 70 → 60 → ...) until the output is ≤100KB
  4. Returns the compressed base64 string for storage

This prevents database bloat and keeps load times fast on mobile connections.

Atomic Vote Counting

Candidate.findByIdAndUpdate(id, { $inc: { vote_count: 1 } }) — MongoDB's $inc operator is atomic at the document level. Concurrent vote submissions for the same candidate cannot produce a race condition or incorrect count.


Project Structure

├── api/
│   ├── index.js          # Express server — all routes, models, middleware
│   ├── package.json      # Backend dependencies (express, mongoose, jwt, sharp...)
│   └── .env.sample       # Environment variable template
│
├── src/
│   ├── components/
│   │   ├── ui/           # Button, Input, Select, Modal, Card, Toast, Badge
│   │   └── DeveloperFab.tsx
│   ├── context/
│   │   └── AppContext.tsx # Global auth state + toast system
│   ├── pages/
│   │   ├── auth/         # AuthPage, LoginForm, RegisterForm
│   │   ├── admin/        # Dashboard, Students, Candidates, Positions,
│   │   │                 # Programs, Reports, Settings
│   │   └── student/      # StudentPage, VotingBallot
│   ├── services/
│   │   └── api.ts        # Axios instance + all API functions + types
│   └── types/
│       └── index.ts      # Shared TypeScript interfaces
│
├── vite.config.ts        # Proxy /api → :3001, host 0.0.0.0, port 5000
└── package.json          # Frontend dependencies

About the Developer

Raldin Casidar — Full-Stack Web Developer

This project was designed and built solo — from system architecture and database schema design, to UI/UX, to backend API implementation and deployment configuration. It demonstrates end-to-end ownership of a production web application: real users, real data, real constraints.

Core competencies demonstrated in this project:

  • Full-stack JavaScript/TypeScript (React, Node.js, Express)
  • REST API design with authentication and role-based access control
  • MongoDB schema design and query optimization
  • Mobile-first responsive UI design
  • Image processing and optimization pipelines
  • Production deployment considerations (environment secrets, static serving, CORS)

Get in touch:


Built with React · Express · MongoDB · TypeScript · Tailwind CSS

About

Election system built for our College of Computing Studies

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages