{"id":29301967,"url":"https://github.com/nzgl-g/votex","last_synced_at":"2025-07-06T23:09:12.572Z","repository":{"id":293155910,"uuid":"968839008","full_name":"nzgl-g/voteX","owner":"nzgl-g","description":"Collaborative platform blockchain-based voting system.","archived":false,"fork":false,"pushed_at":"2025-06-26T07:17:36.000Z","size":4294,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-26T07:37:15.339Z","etag":null,"topics":["blockchain","collaborative","team","voting","voting-system","voting-systems"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nzgl-g.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-18T20:40:41.000Z","updated_at":"2025-06-26T07:17:39.000Z","dependencies_parsed_at":"2025-05-14T01:46:01.539Z","dependency_job_id":"dceb0cd3-63e4-45ca-921b-742c000576ed","html_url":"https://github.com/nzgl-g/voteX","commit_stats":null,"previous_names":["nzgl-g/vote-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nzgl-g/voteX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzgl-g%2FvoteX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzgl-g%2FvoteX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzgl-g%2FvoteX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzgl-g%2FvoteX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nzgl-g","download_url":"https://codeload.github.com/nzgl-g/voteX/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzgl-g%2FvoteX/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263986294,"owners_count":23539812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","collaborative","team","voting","voting-system","voting-systems"],"created_at":"2025-07-06T23:09:06.135Z","updated_at":"2025-07-06T23:09:12.566Z","avatar_url":"https://github.com/nzgl-g.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blockchain Vote System\n\nA full-stack, blockchain-based voting platform with robust KYC, role-based access, and transparent, tamper-proof voting sessions.\n\n---\n\n## Table of Contents\n\n- [Project Overview](#project-overview)\n- [Architecture](#architecture)\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Directory Structure](#directory-structure)\n- [Getting Started](#getting-started)\n- [Frontend](#frontend)\n- [Backend](#backend)\n- [Blockchain](#blockchain)\n- [KYC Service](#kyc-service)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Project Overview\n\nThis 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.\nThis project was developed as part of the requirements for obtaining a Bachelor's degree in Computer Science. The academic report is available here.\n\nNote: The project is still under development and may contain some issues, which will be addressed as soon as we have the availability.\n\nFor deeper documentation u can check this link [here](https://deepwiki.com/nzgl-g/vote-system).\n\n---\n\n## Architecture\n\n- **Frontend**: Next.js app for user interaction, dashboards, and voting.\n- **Backend**: Node.js/Express API for business logic, user/session management, and blockchain interaction.\n- **Blockchain**: Solidity smart contracts for vote sessions and vote recording.\n- **KYC**: Python microservice for document and identity verification.\n\n---\n\n## Features\n\n- **Role-based Dashboards**: Custom interfaces for each user type.\n- **Session Management**: Create, edit, and manage voting sessions.\n- **Blockchain Voting**: All votes are recorded on-chain for transparency.\n- **KYC Integration**: Secure identity verification for voters and candidates.\n- **Team Management**: Team leaders can invite/manage members.\n- **Notifications**: Real-time updates for session events, KYC status, and more.\n\n---\n\n## Tech Stack\n\n- **Frontend**: Next.js, TypeScript, Tailwind CSS, Shadcn UI\n- **Backend**: Node.js, Express, MongoDB, Socket.IO\n- **Blockchain**: Solidity, Hardhat, Ethers.js\n- **KYC**: Python, Flask, OCR, image forensics\n\n---\n\n## Directory Structure\n```\n.\n├── app/           # Next.js frontend  \n├── server/        # Node.js/Express backend  \n├── blockchain/    # Solidity smart contracts \u0026 deployment  \n├── kyc/           # Python KYC microservice  \n├── components/    # Shared frontend components  \n├── services/      # Frontend service modules (API calls)  \n├── docs/          # Additional documentation  \n├── public/        # Static assets  \n├── utils/         # Utility functions  \n├── types/         # TypeScript types  \n└── ...\n```\n\n\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v16+)\n- Python 3.8+\n- MongoDB\n- Docker (optional, for containerized setup)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/nzgl-g/voteX.git\ncd vote-system\n```\n\n### 2. Install Dependencies\n\n#### Frontend \u0026 Backend\n\n```bash\npnpm install\n# or\nnpm install\n```\n\n#### KYC Service\n\n```bash\ncd kyc\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n### 3. Environment Variables\n\n- Copy `.env-docker.example` and `.env_sample` (in `kyc/`) to `.env` files and fill in required values.\n\n### 4. Running the System\n\n#### Docker (Recommended)\n\n```bash\ndocker-compose up --build\n```\n\n#### Manual\n\n- **Frontend**: `pnpm run dev`\n- **Backend**: `cd server \u0026\u0026 npm start`\n- **KYC**: `cd kyc \u0026\u0026 python app.py`\n- **Blockchain**: Deploy contracts with Hardhat (`cd blockchain \u0026\u0026 npx hardhat run scripts/deploy.js`)\n\n---\n\n## Frontend\n\n- Built with Next.js, TypeScript, Tailwind CSS, and Shadcn UI.\n- Role-based dashboards: `/app/team-leader`, `/app/team-member`, `/app/voter-portal`, `/app/candidate-portal`.\n- Session creation, voting, KYC, and notifications.\n\nSee [FRONTEND_README.md](FRONTEND_README.md) for details.\n\n---\n\n## Backend\n\n- Node.js/Express REST API.\n- Handles authentication, session/team management, notifications, and blockchain interaction.\n- MongoDB for data storage.\n- Socket.IO for real-time updates.\n\nSee [server/README.md](server/README.md) for details.\n\n---\n\n## Blockchain\n\n- Solidity smart contracts: `VoteSessionFactory`, `VoteSession`.\n- Hardhat for deployment/testing.\n- All votes and session data are recorded on-chain for transparency.\n\nSee [blockchain/README.md](blockchain/README.md) for details.\n\n---\n\n## KYC Service\n\n- Python Flask microservice for document and identity verification.\n- Integrates with backend for user KYC checks.\n- Uses OCR, image forensics, and metadata analysis.\n\nSee [kyc/README.md](kyc/README.md) for details.\n\n---\n\n## Security\n\n- JWT-based authentication and role-based access control.\n- All sensitive data managed via environment variables.\n- KYC data is handled securely and deleted after processing.\n- Blockchain private keys are never exposed in the codebase.\n\n---\n\n## Contributing\n\n1. Fork the repo\n2. Create your feature branch (`git checkout -b feature/YourFeature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/YourFeature`)\n5. Create a new Pull Request\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n## Documentation\n\n- [Frontend](FRONTEND_README.md)\n- [Backend](server/README.md)\n- [Blockchain](blockchain/README.md)\n- [KYC](kyc/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzgl-g%2Fvotex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnzgl-g%2Fvotex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzgl-g%2Fvotex/lists"}