Documentation

SYSVOTE · for a fair representation

Introduction

SYSVOTE (v3.0.0) is a web-based electronic voting system built on Jakarta EE (the enterprise Java application development platform). Designed for political parties, institutions, and organizations, it enables the simulation and management of complete, transparent electoral processes.

The platform includes a comprehensive administrative dashboard (automated CSV-based voter enrollment, district mapping), a secure voter portal with flexible ID verification, double-vote prevention, as well as real-time result tracking with automatic election lockout at the end of the countdown.

File Structure

SYSVOTE3.0.0/source_code/
├── src/
│   ├── main/                 # Java sources (Controllers, DAO, Models)
│   └── test/                 # Unit tests
├── target/
│   ├── classes/              # Compiled classes
│   └── sysvote3.0-1.0-SNAPSHOTS/
│       ├── assets/
│       │   ├── css/          # Custom styles
│       │   ├── icons/        # Bootstrap Icons
│       │   ├── images/       # Logos, banners
│       │   ├── js/           # Client-side JavaScript
│       │   ├── plugins/      # Third-party plugins
│       │   └── xhr/          # JSP for AJAX requests
│       ├── META-INF/
│       │   └── context.xml   # Application context
│       ├── WEB-INF/
│       │   └── web.xml       # Servlet/JSP mappings
│       └── *.jsp             # Dynamic pages
├── nb-configuration.xml
└── pom.xml                   # Maven dependencies
      

Plugins

SYSVOTE v3.0 Uses the following plugins. Visit the links for documentation and updates.

Configuration

  1. Database server – MySQL recommended (MAMP / WAMP for local).
  2. Database – Create electiondata and import the SQL file from the Setup folder.
  3. Application server – Tomcat 10.1.34+ or JBoss.
  4. Start the Jakarta EE server – Follow your server's documentation.
  5. Ports – MySQL on 3306 (modifiable in the Connexion class). Server on 8080.
  6. JDK / JRE – Install the JDK to compile or the JRE to run.

Build

Installation

  1. Start your server (Tomcat, JBoss, etc.) and access the administration interface.
  2. Deploy the .war file (located in source_code/target) via the application manager.
  3. Optional: Modify the database port in the Connexion class (src/java/dao) if needed.

TIP If you use a Jakarta EE-compatible IDE, you can simply run the application directly.

Docker Setup

RECOMMENDED A pre-configured Docker version is available for those who want to skip the manual server/database setup entirely.

Location

The Docker configuration is located in setup/sysvote-docker, and contains:

setup/sysvote-docker/
├── docker-compose.yml
├── electiondata.sql
├── start.sh     # Linux / macOS
└── start.bat    # Windows
      

Requirements

Usage

  1. Open the sysvote-docker folder.
  2. Run the startup script for your OS:
    • Windows: double-click start.bat
    • Linux / macOS: ./start.sh
  3. Docker will automatically pull the required images and start three containers:
    • sysvote_db – MySQL 8.0 with the electiondata database
    • sysvote_tomcat – the SysVote application
    • sysvote_pma – phpMyAdmin, for database inspection

Access

No manual MySQL, Tomcat, or Maven setup is required — everything runs in isolated containers.

Database Schema

The SysVote database (electiondata) consists of 13 tables organized around the core election management workflow.

Entity Relationship Overview

┌─────────────────────────────────────────────────────────────────────┐ │ SYSVOTE DATABASE │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ settings │ │ members │ │ voters │ │ │ ├──────────────┤ ├──────────────┤ ├──────────────────┤ │ │ │ process_ │ │ ssn (PK) │◄────│ ssn (PK,FK) │ │ │ │ status │ │ firstname │ │ district (FK) │ │ │ │ election_ │ │ lastname │ │ accesscode │ │ │ │ type │ │ birthdate │ │ status │ │ │ │ ageLimit │ │ states │ │ votelog │ │ │ │ country │ │ city │ └──────────────────┘ │ │ │ enableMFA │ │ picture │ │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ │ candidates │ │ districts │ │ │ │ ├──────────────┤ ├──────────────┤ │ │ │ │ scui (PK) │ │ name (PK) │ ◄───────────┘ │ │ │ name │ │ capacity │ │ │ │ picture │ │ centers │ │ │ │ slogan │ │ status │ │ │ │ post │ │ states │ │ │ │ axe │ │ city │ │ │ │ nbvote │ │ location │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ └────────► │ votelog │ │ election_history │ │ │ │ ├──────────────────┤ ├──────────────────┤ │ │ │ │ id (PK) │ │ history_id (PK) │ │ │ │ │ votehour │ │ election_type │ │ │ │ │ axe │ │ edition_year │ │ │ │ │ candidatId (FK) │ │ start_date │ │ │ │ └──────────────────┘ │ end_date │ │ │ └── ── ── ── ── ── ── ── ── ── ─┐ │ total_votes_cast │ │ │ ┌──────────────────────────┐ │ │ winner_candidate │ │ │ │ election_candidate_ │ │ └──────────────────┘ │ │ │ results │ │ │ │ │ ├──────────────────────────┤ │ │ │ │ │ result_id (PK) │ │ │ │ │ │ history_id (FK) ─────────┼───────────│───────────┘ │ │ │ candidate_scui (FK) ──┼───────────┘ │ │ │ candidate_name │ │ │ │ party_id (FK) │ ┌──────────────────────┐ │ │ │ vote_count │ │ political_parties │ │ │ │ vote_percentage │ ├──────────────────────┤ │ │ │ is_winner │ │ party_id (PK) │ │ │ └──────────────────────────┘ │ party_name │ │ │ │ party_code │ │ │ ┌──────────────────────┐ │ logo_path │ │ │ │ identity_settings │ │ color_code │ │ │ ├──────────────────────┤ └──────────────────────┘ │ │ │ id (PK) │ │ │ │ code_name │ ┌──────────────────────┐ │ │ │ full_name │ │ users │ │ │ │ input_mask │ ├──────────────────────┤ │ │ │ regex_pattern │ │ id (PK) │ │ │ └──────────────────────┘ │ name │ │ │ │ username │ │ │ ┌──────────────────────┐ │ password │ │ │ │ coordinates │ │ role │ │ │ ├──────────────────────┤ │ access │ │ │ │ id (PK) │ │ status │ │ │ │ state │ └──────────────────────┘ │ │ │ city │ │ │ │ latitude │ ┌──────────────────────┐ │ │ │ longitude │ │ notifications │ │ │ └──────────────────────┘ ├──────────────────────┤ │ │ │ id (PK) │ │ │ │ class │ │ │ │ message │ │ │ │ victime │ │ │ │ date │ │ │ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘

Table Details

1. settings — Election Parameters

Stores all global election settings including timing, security, and process status.

FieldTypeDescription
process_statusENUMawaiting, launched, stopped, completed
election_typeVARCHAR(100)e.g., "Presidential Election"
edition_yearVARCHAR(50)Year of the election
ageLimitINTMinimum voting age (default: 18)
enableMFABOOLEANMulti-factor authentication toggle
voting_duration_valueINTDuration value (default: 24)
voting_duration_unitVARCHAR(20)HOURS, MINUTES, etc.

2. members — Registered Members

Core table containing all registered individuals. Primary key ssn is referenced by voters.

FieldTypeDescription
ssn (PK)VARCHAR(50)Unique identification number
firstnameVARCHAR(100)First name
lastnameVARCHAR(100)Last name
sexVARCHAR(10)Gender
birthdateVARCHAR(50)Date of birth
statesVARCHAR(100)State of residence
cityVARCHAR(100)City of residence
pictureVARCHAR(250)Profile picture path

3. voters — Voter Registration

Extends members with voting-specific data. Foreign key to members.ssn.

FieldTypeDescription
ssn (PK, FK)VARCHAR(20)References members.ssn (CASCADE DELETE)
district (FK)VARCHAR(50)References districts.name
accesscodeVARCHAR(100)Unique one-time voting code
statusTINYINT(1)0 = inactive, 1 = active
votelogVARCHAR(50)Vote timestamp reference

4. candidates — Election Candidates

FieldTypeDescription
scui (PK)VARCHAR(10)Unique candidate identifier
nameVARCHAR(50)Full name
pictureVARCHAR(100)Photo path
sloganVARCHAR(100)Campaign slogan
postVARCHAR(50)Position running for
axeVARCHAR(50)Political axis / category
nbvoteINTVote counter

5. districts — Electoral Districts

FieldTypeDescription
name (PK)VARCHAR(150)District name
capacityINTNumber of voters
centersINTNumber of voting centers
statusTINYINT(1)1 = active, 0 = inactive
selected_zonesLONGTEXTJSON with territories and polling stations
statesVARCHAR(100)States covered
cityVARCHAR(100)Main city

6. election_history — Archived Elections

FieldTypeDescription
history_id (PK)INTAuto-increment ID
election_typeVARCHAR(100)Type of election
edition_yearINTYear
start_dateDATETIMEStart timestamp
end_dateDATETIMEEnd timestamp
total_votes_castINTTotal votes recorded
blank_votesINTBlank votes count
winner_candidate_nameVARCHAR(150)Winning candidate

7. election_candidate_results — Detailed Results

FieldTypeDescription
result_id (PK)INTAuto-increment
history_id (FK)INTReferences election_history (CASCADE)
candidate_scui (FK)VARCHAR(50)References candidates.scui
candidate_nameVARCHAR(150)Candidate full name
party_id (FK)INTReferences political_parties
vote_countINTNumber of votes
vote_percentageDECIMAL(5,2)Percentage of total
is_winnerTINYINT(1)1 if winner

8. political_parties — Party Information

FieldTypeDescription
party_id (PK)INTAuto-increment
party_nameVARCHAR(100)Full party name
party_codeVARCHAR(10)Short code (unique)
logo_pathVARCHAR(255)Logo file path
color_codeVARCHAR(7)Hex color (#000000)

9. votelog — Vote Tracking Log

FieldTypeDescription
id (PK)INTAuto-increment
votehourTIMESTAMPTime of vote
axeVARCHAR(50)Category/axis
candidatId (FK)VARCHAR(50)References candidates.scui

10. users — Admin & Assistant Accounts

FieldTypeDescription
id (PK)VARCHAR(50)Unique user ID
nameVARCHAR(200)Full name
usernameVARCHAR(50)Login username
passwordVARCHAR(100)MD5 hashed password
roleTINYINT10 = Admin, 101 = Assistant
accessVARCHAR(250)Comma-separated permissions (B,C,D,H,V,S)

11. coordinates — City/State Geo-Data

FieldTypeDescription
id (PK)INTAuto-increment
stateVARCHAR(2)State abbreviation
cityVARCHAR(100)City name
latitudeDECIMAL(10,6)Latitude coordinate
longitudeDECIMAL(10,6)Longitude coordinate

12. identity_settings — ID Configuration

FieldTypeDescription
id (PK)INTAuto-increment
code_nameVARCHAR(20)e.g., "SSN"
full_nameVARCHAR(100)e.g., "Social Security Number"
input_maskVARCHAR(50)e.g., "000-000-000"
regex_patternVARCHAR(255)Validation regex

13. notifications — System Notifications

FieldTypeDescription
id (PK)INTAuto-increment
classINTNotification type/level
messageVARCHAR(200)Notification content
victimeVARCHAR(200)Target user/group
dateTIMESTAMPCreation timestamp

IMPORTANT Foreign key voters.ssn references members.ssn with CASCADE DELETE — deleting a member automatically removes their voter record.

Features & Annotated User Journey

Step-by-step visual workflow and feature walkthrough across the SysVote platform.

1 Access & Authentication Journey

Fig 1.1 — Voter Portal
Voter Access Code Login

[A1] Voter Login: Simple single-field entry for the generated voter access code. Includes automatic validation and double-vote check before granting access to the voting workflow.

Fig 1.2 — Admin Portal
Administrator Portal Login

[A2] Admin Login: Role-based credentials interface (Username & Password). Secured with MD5 hash validation and session-level permissions.

SECURE Dual login architecture cleanly separates anonymous voter access from administrative management.


2 System Navigation & Live Countdown

Fig 2.1 — Global Header
Header Navigation Bar

[B1] Live Timer: Dynamic countdown displaying remaining election time. Triggers an automatic system-wide lockout once time expires.

[B2] Quick Actions: Status indicators, real-time alerts, and one-click navigation across management modules.


3 Administrative Home Dashboard

Fig 3.1 — Real-Time Metrics
Live Dashboard Charts

[C1] Live Analytics: Map.js visualization showing real-time vote progression and lead distribution among candidates.

Fig 3.2 — Key Performance Indicators
Electoral Statistics Summary

[C2] Global Indicators: KPI cards highlighting total enrolled voters, total votes cast, turnout percentage, and blank ballots.


4 Voter Enrollment & Access Generation

Enrollment Workflows

[D1] Single Entry Drawer: Offcanvas form for registering individuals with real-time IMask input formatting (SSN / NID).

[D2] Bulk CSV Upload: Automated batch processing via DropzoneJS. Displays comprehensive error/success breakdown modal upon upload.

[D3] Member conversion: Integrated DataTables filtering to activate qualified members as active voters based on age and district rules.

Fig 4.1 — Data Table
Voter Management Interface
Fig 4.2 — Code Generator
Voter Detail & Access Code Drawer

[D4] Access Code Drawer: View voter credentials, generate or reset unique single-use access codes, and preview digital ID card generation.


5 Candidate & Campaign Management

Fig 5.1 — Candidate Profile Grid
Candidate Roster Grid

[E1] Profile Management: Add candidate records complete with slogans, assigned political party, photo uploads, and current vote tally tracking.


6 Electoral Districts & Geolocation

[F1] Regional Controls: Configure district capacity limits, associate voting centers, and assign territory boundaries.

[F2] Geographic Map: Interactive Leaflet map rendering regional centers, state boundaries, and voter distribution density.

Fig 6.1 — Interactive Map
District Management & Map

7 Drag & Drop Voting Experience

Fig 7.1 — Digital Ballot
Drag and Drop Voting Screen

[G1] Intuitive Drag-and-Drop: Voters select their chosen candidate card and drag it into the official digital ballot box.

[G2] Single-Use Lockout: Backend verification invalidates the access code immediately upon ballot submission to prevent multiple attempts.

Fig 7.2 — Final Confirmation
Ballot Confirmation Window

[G3] Choice Confirmation: Explicit confirmation prompt displaying candidate selection prior to encrypting and logging the vote.


8 Live Election Results & Geospatial Analytics

Fig 8.1 — Real-Time Tallies
Live Election Results Charts

[H1] Dynamic Charts: Real-time vote tallies updating dynamically without requiring page refreshes.

Fig 8.2 — Regional Breakdown
Heatmap District Results

[H2] Regional Breakdown: Color-coded district map illustrating regional victory margins and leading candidates by territory.


9 System Configuration & Parameters

Fig 9.1 — Rule Config
Security Settings Panel

[I1] Election Rules: Define election type, edition year, minimum voting age restriction, and set total duration (hours/minutes).

Fig 9.2 — Mask Config
Security Settings Panel

[I2] Timing Control: Define a delay to stop candidates subscription and duration of vote process.

Fig 9.3 — Security Policies
Security Settings Panel

[I2] Identity Masks: Define system-wide mask rules (e.g., SSN, CIN) and regular expressions for ID verification.

Fig 9.4 — Global Settings
Advanced System Controls

[I3] Security Options: MFA enforcement toggles, login attempt limits, and system event notification preferences.

Architecture

SysVote follows the Model-View-Controller (MVC) pattern with Jakarta EE technologies.

Project Structure Overview

┌─────────────────────────────────────────────────────────────┐
│                     SYSVOTE MVC ARCHITECTURE                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   VIEW (JSP)                        │    │
│  │  • assets/ (CSS, JS, images, plugins)               │    │
│  │  • *.jsp pages (dynamic rendering)                  │    │
│  │  • xhr/ (AJAX response fragments)                   │    │
│  └────────────────────┬────────────────────────────────┘    │
│                       │                                     │
│                       ▼                                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │               CONTROLLER (Servlets)                  │   │
│  │  • HttpServletRequest / Response handling            │   │
│  │  • Session management                                │   │
│  │  • Request routing and validation                    │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                     │
│                       ▼                                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              DAO (Data Access Objects)               │   │
│  │  • JDBC database connections                         │   │
│  │  • CRUD operations                                   │   │
│  │  • Transaction management                            │   │
│  │  • Query execution & result mapping                  │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                     │
│                       ▼                                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              MODEL (JavaBeans / POJOs)               │   │
│  │  • Data representation (candidates, voters, etc.)    │   │
│  │  • Business logic methods                            │   │
│  │  • Relationships between entities                    │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                 DATABASE (MySQL)                     │   │
│  │  • 13 tables with foreign key constraints            │   │
│  │  • Stored procedures (if any)                        │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
        

Key Technologies

Flow Overview

  1. User request → Servlet (Controller) intercepts the request.
  2. Servlet calls appropriate DAO methods to interact with the database.
  3. DAO executes queries and returns JavaBean objects (Model).
  4. Servlet sets attributes and forwards the request to a JSP (View).
  5. JSP renders the response with dynamic data from the Model.
  6. AJAX requests bypass full page reloads for smoother user experience.

Customization Guide

Learn how to personalize SysVote to match your organization's branding and requirements.

1. Branding (Colors & Logos)

Logo Replacement

  • Favicon: Replace src/main/webapp/assets/images/sysvote.ico with your own favicon.
  • Header Logo: Located in assets/images/ — update the logo file and reference it in the JSP header.
  • Login Page Logo: Replace src/main/webapp/assets/images/logo.png or the image referenced in login.jsp.

Color Customization

  • Primary Color: Edit the :root CSS variables in assets/css/custom.css:
:root {
  --primary-color: #1a2b4c;
  --primary-light: #2a3f64;
  --secondary-color: #eef2f6;
  --accent-color: #7c3aed;
}
        
  • Button Colors: Override Bootstrap variables in assets/css/override.css.

2. CSS Styling Overrides

SysVote uses Bootstrap 5.3.3 as the base framework. To customize without modifying core files:

  • Create a assets/css/custom.css file (if not already present).
  • Add your custom styles — they will override Bootstrap and default styles.
  • Example customizations:
/* Custom card styles */
.custom-card {
  border-radius: 20px;
  box-shadow: 0 8px 24px rgba(0,0,0,0.08);
  border: 1px solid #e9edf2;
}

/* Custom typography */
h1, h2, h3 {
  font-family: 'Inter', sans-serif;
  letter-spacing: -0.02em;
}

/* Custom dashboard colors */
.dashboard-stat {
  background: linear-gradient(135deg, #1a2b4c 0%, #2a3f64 100%);
  color: white;
}
        

IMPORTANT Avoid editing Bootstrap core files directly. Always use separate custom CSS files.

3. ID Configuration

Modify identification rules in the Settings section of the admin dashboard or directly in the identity_settings table:

  • code_name: Short identifier (e.g., "SSN", "NID", "CIN")
  • full_name: Full description (e.g., "Social Security Number", "National ID")
  • input_mask: Display mask (e.g., "000-000-000", "000-00-0000")
  • regex_pattern: Validation regular expression
-- Example: Add a National ID configuration
INSERT INTO identity_settings (code_name, full_name, input_mask, regex_pattern)
VALUES ('NID', 'National ID', '000-000000-0', '^\\d{3}-\\d{6}-\\d$');
        

4. Election Configuration

All election parameters are stored in the settings table. Modify them via the admin dashboard or directly in the database:

  • election_type: Change the election name (e.g., "Presidential Election", "General Election")
  • edition_year: Update the election year
  • ageLimit: Modify the minimum voting age
  • voting_duration_value & unit: Set the voting period (e.g., 24 HOURS, 30 MINUTES)
  • process_status: Manually control the election flow (awaiting, launched, stopped, completed)

5. Adding New Political Parties

Parties can be added through the admin dashboard or via SQL:

INSERT INTO political_parties (party_name, party_code, logo_path, color_code)
VALUES ('New Party', 'NP', 'new_party.png', '#FF5733');
        

After adding, they will appear in candidate registration forms and results displays.

Troubleshooting

Common installation and runtime issues and their solutions.

ERROR Database connection fails
Solution: Check that MySQL is running and the electiondata database exists. Verify connection parameters in the Connexion class (src/java/dao).
jdbc:mysql://localhost:3306/electiondata
TIP If using Docker, ensure the sysvote_db container is running.
ERROR HTTP 404 — Page not found
Solution: Ensure the WAR file is properly deployed and the context path is correct. Try accessing http://localhost:8080/sysvote3.0 or the path defined in your server.
TIP Check Tomcat's webapps folder to confirm the application is deployed.
ERROR ClassNotFoundException / NoClassDefFoundError
Solution: This indicates missing dependencies. Run mvn clean install from the project root to download all required JAR files. Ensure all dependencies are listed in pom.xml.
TIP Check that your server supports Jakarta EE (Tomcat 10+).
ERROR Access code not working for voter login
Solution: Verify that the voter's status is set to 1 (active) in the voters table. Check if the access code has already been used — each code is single-use. You can regenerate a new code from the voter management panel.
TIP Check the votelog table to see if a vote has already been recorded for that code.
ERROR Server not starting (Port 8080 already in use)
Solution: Change the server port in your Tomcat configuration (conf/server.xml) or stop the process using the port.
Windows: netstat -ano | findstr :8080 then taskkill /PID <PID> /F
Linux/macOS: sudo lsof -i :8080 then kill -9 <PID>
WARNING Maven build fails
Solution: Ensure you have an internet connection for dependency downloads. Clear the local Maven repository (~/.m2/repository) and rebuild.
mvn clean install -U
TIP Check that your pom.xml uses the correct repository URLs.
WARNING Election countdown not starting
Solution: Verify that the process_status in the settings table is set to launched. Check that voting_duration_value and voting_duration_unit are correctly configured.
TIP The countdown starts when the election is launched from the admin panel or when process_status is updated.

Limitations

Version 3.0: Efficiency at very large scale has not yet been proven. The logic is designed for presidential election simulations. Security is not 100% guaranteed; we recommend an audit by a specialist before professional use. Improvements are planned for future releases.

  • Scale: Optimized for up to 50,000 voters in current configuration.
  • Security: Basic security implemented; enterprise-grade audit recommended.
  • Real-time: Updates every 5 seconds by default — can be adjusted in JavaScript.
  • Backup: Manual backup currently; automated backup planned for v3.1.

Licenses

1. License Agreement

Purchasing this application implies acceptance of these terms.

2. Right to Modify

You are authorized to modify the source code as needed for your organization.

3. Redistribution

Redistribution of the software in its original form is prohibited without substantial modifications. Changes must be clearly mentioned.

4. Commercial Use

Use without prior purchase is prohibited. Commercial use requires a valid license.

5. Intellectual Property

All rights remain the property of MajOrWare IT Solutions.

6. Acceptance

Use of the application constitutes acceptance of these terms.

Support & Updates

Image Credits

  • Freepik — UI icons and design assets
  • Google Images — Reference images used in documentation
  • Flaticon — Icon sets used in the application

Contact Us

Company: MajOrWare IT Solutions

Instagram: @majorware

LinkedIn: Renald Occean

Email: contact@majorware.net

Website: www.majorware.net

Need customization or assistance? Our engineering team at MajOrWare IT Solutions is ready to help you adapt SysVote to your organization's specific needs.

Version History

  • v3.0.0 — Current release: Major UI overhaul, Docker support, enhanced security features, CSV import.
  • v2.0.0 — Added multi-district support, real-time results, and Leaflet maps.
  • v1.0.0 — Initial release: Basic voting system with admin panel.

Documentation SysVote 3.0 · MajOrWare IT Solutions · All rights reserved