A full-stack, blockchain-based voting platform with robust KYC, role-based access, and transparent, tamper-proof voting sessions.

• Project Overview
• Architecture
• Features
• Tech Stack
• Directory Structure
• Getting Started
• Frontend
• Backend
• Blockchain
• KYC Service
• Security
• Contributing
• License

This system enables secure, transparent, and decentralized voting using blockchain technology. It supports multiple user roles (Team Leader, Team Member, Candidate, Voter) and integrates a KYC process for identity verification. This project was developed as part of the requirements for obtaining a Bachelor's degree in Computer Science. The academic report is available here.

Note: The project is still under development and may contain some issues, which will be addressed as soon as we have the availability.

For deeper documentation u can check this link here.

• Frontend: Next.js app for user interaction, dashboards, and voting.
• Backend: Node.js/Express API for business logic, user/session management, and blockchain interaction.
• Blockchain: Solidity smart contracts for vote sessions and vote recording.
• KYC: Python microservice for document and identity verification.

• Role-based Dashboards: Custom interfaces for each user type.
• Session Management: Create, edit, and manage voting sessions.
• Blockchain Voting: All votes are recorded on-chain for transparency.
• KYC Integration: Secure identity verification for voters and candidates.
• Team Management: Team leaders can invite/manage members.
• Notifications: Real-time updates for session events, KYC status, and more.

• Frontend: Next.js, TypeScript, Tailwind CSS, Shadcn UI
• Backend: Node.js, Express, MongoDB, Socket.IO
• Blockchain: Solidity, Hardhat, Ethers.js
• KYC: Python, Flask, OCR, image forensics

.
├── app/           # Next.js frontend  
├── server/        # Node.js/Express backend  
├── blockchain/    # Solidity smart contracts & deployment  
├── kyc/           # Python KYC microservice  
├── components/    # Shared frontend components  
├── services/      # Frontend service modules (API calls)  
├── docs/          # Additional documentation  
├── public/        # Static assets  
├── utils/         # Utility functions  
├── types/         # TypeScript types  
└── ...

• Node.js (v16+)
• Python 3.8+
• MongoDB
• Docker (optional, for containerized setup)

git clone https://github.com/nzgl-g/voteX.git
cd vote-system

pnpm install
# or
npm install

cd kyc
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• Copy .env-docker.example and .env_sample (in kyc/) to .env files and fill in required values.

docker-compose up --build

• Frontend: pnpm run dev
• Backend: cd server && npm start
• KYC: cd kyc && python app.py
• Blockchain: Deploy contracts with Hardhat (cd blockchain && npx hardhat run scripts/deploy.js)

• Built with Next.js, TypeScript, Tailwind CSS, and Shadcn UI.
• Role-based dashboards: /app/team-leader, /app/team-member, /app/voter-portal, /app/candidate-portal.
• Session creation, voting, KYC, and notifications.

See FRONTEND_README.md for details.

• Node.js/Express REST API.
• Handles authentication, session/team management, notifications, and blockchain interaction.
• MongoDB for data storage.
• Socket.IO for real-time updates.

See server/README.md for details.

• Solidity smart contracts: VoteSessionFactory, VoteSession.
• Hardhat for deployment/testing.
• All votes and session data are recorded on-chain for transparency.

See blockchain/README.md for details.

• Python Flask microservice for document and identity verification.
• Integrates with backend for user KYC checks.
• Uses OCR, image forensics, and metadata analysis.

See kyc/README.md for details.

• JWT-based authentication and role-based access control.
• All sensitive data managed via environment variables.
• KYC data is handled securely and deleted after processing.
• Blockchain private keys are never exposed in the codebase.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/YourFeature)
5. Create a new Pull Request

MIT

• Frontend
• Backend
• Blockchain
• KYC