Bright Future - Web Voting System

🎓 A modern, full-stack student awards voting platform featuring events, nominee management, dashboards, real-time notifications, and automated result generation.

Spring Boot 3 API · React 18 / Vite UI · PostgreSQL / H2 Database

---

✨ Overview

Bright Future is a comprehensive digital voting solution designed for educational institutions. It allows students to register securely, sign in, and cast votes in active campus award events. Administrators benefit from a robust management suite to handle events, categories, nominees, student approvals, send notifications, view analytical dashboards, and publish automated result reports (PDF/CSV/Excel).

This repository contains both the Spring Boot API Backend and the React/Vite Frontend for seamless development and deployment.

🏗️ Project Architecture & File Structure

The project is structured into distinct frontend and backend modules, embracing Domain-Driven Design (DDD) principles on the backend and component-based routing on the frontend.

Repository Layout

.
├── backend/            # Spring Boot REST API, security, JPA, reports, and mail
├── frontend/           # React/Vite SPA with Tailwind CSS
├── docker-compose.yml  # Multi-container deployment configuration
├── Dockerfile          # Unified Docker build file
├── data/               # Local H2 database files (development)
└── docs/               # Documentation assets (logos, diagrams)

🔌 Backend Architecture (backend/src/main/java/com/example/votingsystem/)

The backend is highly modularized into distinct domains:

• admin/: Security configuration (JWT, Spring Security), user role management, and initial data seeding (DataSeeder).
• common/: Shared utilities, global exception handling (@ControllerAdvice), and SPA redirect routing.
• dashboard/: Analytics, KPI generation, and metrics retrieval for the admin dashboard.
• export/: Data export services generating PDF and Excel reports for events and results.
• nominee/: Nominee entity management and CRUD operations.
• notification/: Email and in-app notification services.
• publicapi/: Unauthenticated endpoints for public event discovery.
• result/: Complex business logic for vote calculation, tallying, and winner determination.
• student/: Student registration, verification, and admin approval workflows.
• voting/: Core voting logic, vote casting, and vote validation.

🌐 Frontend Architecture (frontend/src/modules/)

The React application follows a feature-based folder structure:

• admin/: Screens for managing system users, event creation, and student approvals.
• dashboard/: Analytical views, charts, and metric visualizations for administrators.
• nominee/: Interfaces for creating, editing, and displaying award nominees.
• notifications/: Components for displaying user alerts and system notifications.
• results/: Data tables and charts showing live voting trends and final winners.
• voting/: The core student-facing interface for selecting categories and casting votes.

🧰 Prerequisites

Ensure your development environment meets the following requirements:

• Java 17 or higher
• Node.js 18 or newer
• npm or yarn
• Docker (optional, for containerized PostgreSQL deployment)

🚀 Running Locally (Development Mode)

You can run the application using the local H2 in-memory database or a local PostgreSQL instance.

1. Start the Backend API

The backend includes a Maven wrapper, so no global Maven installation is required. It runs on http://localhost:8080.

cd backend
# The wrapper script will automatically locate your JAVA_HOME
.\mvnw.cmd spring-boot:run

2. Start the Frontend UI

The Vite development server provides Hot Module Replacement (HMR). It runs on http://localhost:5173.

cd frontend
npm install
npm run dev

🐳 Deploy with PostgreSQL & Docker Compose

Deploy the full-stack platform (React frontend + Spring Boot backend + PostgreSQL database) with a single command:

docker-compose up --build -d

This starts:

• PostgreSQL 16 database container listening on port 5432
• Spring Boot & React Unified application container listening on port 8080

To stop the deployment:

docker-compose down

🔐 Default Admin Credentials

The system automatically seeds the database with the following credentials upon startup:

• Username: admin
• Password: 123

(Additional test student accounts are also generated. Check DataSeeder.java for exact details).

⚙️ Environment Configuration

Configuration properties are managed via .env files and application.yml.

• Backend: backend/src/main/resources/application.yml. Copy backend/.env.example to backend/.env to configure your PostgreSQL connection and JWT secrets.
• Frontend: Copy frontend/.env.example to frontend/.env to set the VITE_API_BASE_URL.

Essential Backend Variables:

• SPRING_DATASOURCE_URL (e.g., jdbc:postgresql://localhost:5432/votingsystem)
• SPRING_DATASOURCE_USERNAME
• SPRING_DATASOURCE_PASSWORD
• APP_JWT_SECRET (Must be a secure 256-bit key)

✅ Quality Checks & Testing

Run backend tests:

cd backend
.\mvnw.cmd test

Run frontend linting and production build:

cd frontend
npm run lint
npm run build