Skip to content

README.md

Latest commit

 

History

History
337 lines (242 loc) · 9.63 KB

README.md

File metadata and controls

337 lines (242 loc) · 9.63 KB

PS3Stack Voting System

A comprehensive microservices-based electronic voting system built with Ballerina and Next.js, featuring real-time monitoring, census management, and AI-powered support.

🏗️ Architecture Overview

This system follows a microservices architecture with the following components:

  • API Gateway - Central routing and authentication hub
  • Auth Service - User authentication and authorization
  • Election Service - Election and candidate management
  • Voter Service - Voting operations and voter check-in
  • Support Service - AI-powered chatbot support
  • Census Service - Population census management
  • Client Application - Next.js frontend with real-time UI

📊 Sequence Diagram for election

alt text

📊 Sequence Diagram for census

alt text

🚀 Quick Start

Prerequisites

  • Ballerina (Swan Lake Update 8 or later)
  • Node.js (20+ recommended)
  • npm or yarn
  • Docker (optional, for containerized deployment)

1. Clone the Repository

git clone https://github.com/PS3stack/ps3stack-ballerina-competition.git
cd ps3stack-ballerina-competition

2. Start Backend Services

# Start all microservices (run each in a separate terminal)

# Auth Service
cd ../services/auth_service
bal run

# Election Service
cd ../election_service
bal run

# Voter Service  
cd ../voter_service
bal run

# Support Service
cd ../support_service
bal run

# Census Service
cd ../census_service
bal run

# API Gateway
cd api_gateway
bal run

# After running the API Gateway you can see the microservices are up and running.

3. Start Frontend

cd client
npm install
npm run dev

4. Access the Application

🔑 API Keys Configuration

Required API Keys

The Support Service requires an OpenAI API key for AI-powered chatbot functionality:

  1. Obtain OpenAI API Key:

    • Visit OpenAI Platform
    • Create an account or sign in
    • Navigate to "API Keys" section
    • Click "Create new secret key"
    • Copy the generated key (starts with sk-)

  2. Configure the Key:

    • Navigate to services/support_service/
    • Copy Config.toml.example to Config.toml
    • Replace the placeholder with your actual API key:
    HTTP_PORT = 8083
OPENAI_API_KEY = "your-actual-openai-api-key-here"

Environment Files

Each service includes .toml.example files with placeholder values. Copy these to the actual config files and replace placeholders with real values:

  • api_gateway/Config.toml.example → Config.toml
  • services/*/Config.toml.example → Config.toml
  • client/.env.example → .env.local

Important: Never commit actual API keys to version control. The .example files are safe to commit as they contain only placeholders.

🗄️ Database Setup

Database Restoration

This project includes a pre-configured database dump with sample data including elections, candidates, and user accounts.

Database Dump Location: database/database.bak

Restore Database with Neon DB

To repopulate your Neon database with the sample data:

pg_restore -v -d "<neon_database_connection_string>" database/database.bak

Example:

pg_restore -v -d "postgresql://username:password@host:5432/database?sslmode=require" database/database.bak

Database Contents

The database dump includes:

  • Sample Elections: Pre-configured elections with candidates and photos
  • User Accounts: Demo accounts for all user roles (admin, observer, field staff, polling staff, voters)
  • Census Data: Sample population and household records
  • System Configuration: Initial setup for all microservices

Manual Database Setup

If you prefer to set up the database manually, each service includes:

  • Schema definitions in service README files
  • Migration scripts in database_migration.sql files
  • Sample data creation in service initialization code

Note: The database connection strings are configured in each service's Config.toml file.

🏛️ System Components

Component Port Description
API Gateway 8080 Central routing, authentication, CORS handling
Auth Service 8085 JWT authentication, role-based access
Election Service 8082 Election management, candidates, observers
Voter Service 8084 Voting operations, voter check-in
Support Service 8083 AI chatbot, help system
Census Service 8081 Population census, household management
Client App 3000 Next.js frontend application

👥 User Roles & Access

Admin (Role ID: 1)

  • Full system access
  • Election management
  • User management
  • System monitoring
  • Demo Login: admin@test.com / password123

Observer (Role ID: 2)

  • Election monitoring
  • Results viewing
  • Report generation

Field Staff (Role ID: 3)

  • Census data collection
  • Household surveys
  • Area assignments

Polling Staff (Role ID: 4)

  • Voting operations
  • Voter check-in
  • Ballot management

🛡️ Security Features

  • JWT Authentication with secure token validation
  • Role-based Access Control (RBAC)
  • CORS Protection for cross-origin requests
  • Input Validation and sanitization
  • Secure Cookie handling
  • API Rate Limiting (configurable)

🔄 API Endpoints

Core Endpoints

POST /api/auth/admin/login          # Admin authentication
POST /api/auth/observer/login       # Observer authentication
POST /api/auth/field_staff/login    # Field staff authentication
POST /api/auth/polling_staff/login  # Polling staff authentication

GET  /api/election                  # List elections
POST /api/election                  # Create election
GET  /api/election/{id}            # Get election details

POST /api/voters/cast              # Cast vote
POST /api/voters/check-in          # Voter check-in

POST /api/support/chat             # AI chatbot
GET  /api/support/health           # Service health

GET  /api/census                   # Census projects
POST /api/census                   # Create census project

See individual service README files for complete API documentation.

🧪 Testing

Demo Accounts

Role Email Password Access Level
Admin admin@test.com password123 Full system access
Observer observer@test.com password123 Read-only monitoring
Field Staff field@test.com password123 Census operations
Polling Staff polling@test.com password123 Voting operations

Health Checks

# Check all services
curl http://localhost:8080/health

# Individual service health
curl http://localhost:8085/auth/health
curl http://localhost:8082/election/health
curl http://localhost:8084/voters/health
curl http://localhost:8083/support/health
curl http://localhost:8081/census/health

📝 Development

Project Structure

ps3stack-ballerina-competition/
├── api_gateway/                 # API Gateway service
├── services/                    # Microservices
│   ├── auth_service/           # Authentication service
│   ├── election_service/       # Election management
│   ├── voter_service/          # Voting operations
│   ├── support_service/        # AI support system
│   └── census_service/         # Census management
├── client/                     # Next.js frontend
└── docs/                       # Documentation

Development Workflow

  1. Backend Development: Modify Ballerina services in services/ or api_gateway/
  2. Frontend Development: Work in client/ directory
  3. Testing: Use the demo accounts for end-to-end testing
  4. API Testing: Use tools like Postman or curl for API testing

Configuration Management

All services use Config.toml files for configuration:

  • Copy .toml.example files to Config.toml
  • Set appropriate values for your environment
  • Never commit actual API keys or sensitive data

🚢 Deployment

Docker Deployment (Recommended)

# Build and run with Docker Compose
docker-compose up --build

Manual Deployment

  1. Build each Ballerina service:
cd services/auth_service && bal build
cd ../election_service && bal build
# ... repeat for each service
  1. Build frontend:
cd client && npm run build
  1. Deploy to your hosting platform of choice

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

  • AI Support: Use the built-in chatbot (accessible after login)
  • Issues: Create a GitHub issue for bugs or feature requests
  • Documentation: Check individual service README files
  • Community: Join our development community

🏆 Acknowledgments

  • Built for the Ballerina Programming Competition
  • Powered by Ballerina Swan Lake
  • Frontend built with Next.js and Tailwind CSS
  • AI features powered by OpenAI

PS3Stack Team - Building the future of democratic technology