{"id":31793510,"url":"https://github.com/tolstoyj/go-voting-blockchain","last_synced_at":"2026-05-02T17:35:10.308Z","repository":{"id":318075702,"uuid":"1069915693","full_name":"Tolstoyj/go-voting-blockchain","owner":"Tolstoyj","description":"🗳️ Production-ready blockchain-based voting system built with Go. Features secure cryptographic operations, real-time results, and seamless deployment capabilities.","archived":false,"fork":false,"pushed_at":"2025-10-04T22:47:37.000Z","size":7150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T23:33:17.005Z","etag":null,"topics":["api","blockchain","cryptography","docker","go","golang","postgresql","redis","rest","security","voting"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tolstoyj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-04T21:51:45.000Z","updated_at":"2025-10-04T22:43:26.000Z","dependencies_parsed_at":"2025-10-04T23:43:48.973Z","dependency_job_id":null,"html_url":"https://github.com/Tolstoyj/go-voting-blockchain","commit_stats":null,"previous_names":["tolstoyj/go-voting-blockchain"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Tolstoyj/go-voting-blockchain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tolstoyj%2Fgo-voting-blockchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tolstoyj%2Fgo-voting-blockchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tolstoyj%2Fgo-voting-blockchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tolstoyj%2Fgo-voting-blockchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tolstoyj","download_url":"https://codeload.github.com/Tolstoyj/go-voting-blockchain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tolstoyj%2Fgo-voting-blockchain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004913,"owners_count":26083802,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api","blockchain","cryptography","docker","go","golang","postgresql","redis","rest","security","voting"],"created_at":"2025-10-10T18:19:11.753Z","updated_at":"2025-10-10T18:19:12.546Z","avatar_url":"https://github.com/Tolstoyj.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🗳️ Go Voting Blockchain\n\n[![Go Version](https://img.shields.io/badge/go-1.21+-blue.svg)](https://golang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)\n[![Railway Ready](https://img.shields.io/badge/railway-ready-0B0D0E.svg)](https://railway.app/)\n\nA production-ready blockchain-based voting system built with Go, featuring enterprise-grade security, JWT authentication, role-based access control, and comprehensive monitoring capabilities.\n\n## ✨ Features\n\n### 🔐 Security \u0026 Authentication (Phase 1)\n- **JWT Authentication**: Secure token-based authentication system\n- **Role-Based Access Control**: Admin and voter roles with proper permissions\n- **Rate Limiting**: Sliding window rate limiting with multiple tiers\n- **Input Validation**: Comprehensive validation and sanitization\n- **Error Handling**: Professional error handling and recovery middleware\n- **Request Logging**: Complete API monitoring and logging system\n- **Digital Signatures**: RSA 2048-bit encryption for vote authentication\n\n### ⛓️ Blockchain Core\n- **Secure Blockchain**: Proof-of-Work consensus with adjustable difficulty\n- **Signature Verification**: Cryptographic proof of vote authenticity\n- **Block Integrity**: SHA-256 hashing for tamper-proof blocks\n- **Mining System**: Configurable mining difficulty and automatic block creation\n\n### 🚀 Performance \u0026 Scalability\n- **RESTful API**: High-performance Gin framework\n- **Persistence**: PostgreSQL and Redis support for data durability\n- **Connection Pooling**: Optimized database connection management\n- **Concurrent Processing**: Asynchronous operations for better performance\n- **Real-time Results**: Live vote tallying and statistics\n\n### 🛠️ Developer Experience\n- **Comprehensive Testing**: Automated security and integration tests\n- **Development Tools**: Complete development environment setup\n- **CI/CD Pipeline**: GitHub Actions for automated testing and deployment\n- **Documentation**: Extensive documentation and guides\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────┐\n│                    Client Applications                │\n│                 (Web, Mobile, CLI)                    │\n└──────────────────────────────────────────────────────┘\n                            │\n                            ▼\n┌──────────────────────────────────────────────────────┐\n│                    REST API (Gin)                     │\n│                    Port: 8080                         │\n└──────────────────────────────────────────────────────┘\n                            │\n┌──────────────────────────────────────────────────────┐\n│                  Blockchain Core                      │\n│         (Blocks, Mining, Verification)                │\n└──────────────────────────────────────────────────────┘\n                            │\n┌──────────────────────────────────────────────────────┐\n│                   Persistence Layer                   │\n│          PostgreSQL (Primary) + Redis (Cache)         │\n└──────────────────────────────────────────────────────┘\n```\n\n## 🚀 Quick Start\n\n### Local Development\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/tolstoyjustin/go-voting-blockchain.git\ncd go-voting-blockchain\n```\n\n2. **Install dependencies**\n```bash\ngo mod download\n```\n\n3. **Set up environment**\n```bash\ncp .env.example .env\n# Edit .env with your configuration\n```\n\n4. **Run the application**\n```bash\ngo run cmd/api/main.go\n```\n\nThe API will be available at `http://localhost:8080`\n\n### Docker Deployment\n\n```bash\ndocker build -t voting-blockchain .\ndocker run -p 8080:8080 voting-blockchain\n```\n\n## ☁️ Railway Deployment\n\n### One-Click Deploy\n\n[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template)\n\n**Note**: This will create a new Railway project with your voting blockchain system.\n\n### Manual Deployment\n\n1. **Create a new Railway project**\n```bash\nrailway login\nrailway init\n```\n\n2. **Add PostgreSQL database**\n```bash\nrailway add postgresql\n```\n\n3. **Add Redis (optional)**\n```bash\nrailway add redis\n```\n\n4. **Deploy**\n```bash\nrailway up\n```\n\nRailway will automatically:\n- Detect the Go application\n- Install dependencies\n- Build the application\n- Set up environment variables\n- Configure health checks\n- Deploy with automatic SSL\n\n### Environment Variables for Railway\n\nRailway automatically provides:\n- `PORT`: Server port (auto-assigned)\n- `DATABASE_URL`: PostgreSQL connection string\n- `REDIS_URL`: Redis connection string (if added)\n\n## API Endpoints\n\n### 🔓 Public Endpoints\n- `GET /` - API status and blockchain info\n- `GET /health` - Health check endpoint\n- `POST /register` - Register a new voter\n- `GET /polls` - List all polls\n- `GET /polls/:poll_id` - Get poll details\n- `GET /results/:poll_id` - Get poll results\n- `GET /blockchain/verify` - Verify blockchain integrity\n- `GET /blockchain/blocks` - Get recent blocks\n- `GET /blockchain/stats` - Get blockchain statistics\n\n### 🔐 Authentication Endpoints\n- `POST /auth/login` - Admin login\n- `POST /auth/voter-login` - Voter login\n- `POST /auth/refresh` - Refresh JWT token\n- `GET /auth/me` - Get current user info\n\n### 👤 Authenticated Endpoints (Voter)\n- `POST /vote` - Cast a vote\n- `GET /voter/:voter_id/history` - Get voter's voting history\n\n### 👑 Admin Endpoints\n- `POST /admin/polls` - Create a new poll\n- `POST /admin/blockchain/mine` - Manually mine pending votes\n\n## API Usage Examples\n\n### 🔐 Authentication\n\n#### Admin Login\n```bash\ncurl -X POST http://localhost:8080/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"admin\",\n    \"password\": \"admin123\"\n  }'\n```\n\n#### Voter Login\n```bash\ncurl -X POST http://localhost:8080/auth/voter-login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"voter_id\": \"voter-uuid\",\n    \"private_key\": \"-----BEGIN RSA PRIVATE KEY-----...\"\n  }'\n```\n\n### 👤 Voter Operations\n\n#### Register a Voter\n```bash\ncurl -X POST http://localhost:8080/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"voter@example.com\",\n    \"name\": \"John Doe\",\n    \"department\": \"Engineering\"\n  }'\n```\n\n#### Cast a Vote (with Authentication)\n```bash\ncurl -X POST http://localhost:8080/vote \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \\\n  -d '{\n    \"poll_id\": \"poll-uuid\",\n    \"voter_id\": \"voter-id\",\n    \"choice\": \"Go\",\n    \"signature\": \"signature-string\"\n  }'\n```\n\n### 👑 Admin Operations\n\n#### Create a Poll (Admin Only)\n```bash\ncurl -X POST http://localhost:8080/admin/polls \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer ADMIN_JWT_TOKEN\" \\\n  -d '{\n    \"title\": \"Best Programming Language\",\n    \"description\": \"Vote for your favorite language\",\n    \"options\": [\"Go\", \"Python\", \"JavaScript\", \"Rust\"],\n    \"creator\": \"Admin\",\n    \"duration_hours\": 24,\n    \"is_anonymous\": false\n  }'\n```\n\n#### Mine Pending Votes (Admin Only)\n```bash\ncurl -X POST http://localhost:8080/admin/blockchain/mine \\\n  -H \"Authorization: Bearer ADMIN_JWT_TOKEN\"\n```\n\n### 📊 Public Operations\n\n#### Get Poll Results\n```bash\ncurl http://localhost:8080/results/poll-uuid\n```\n\n#### Verify Blockchain\n```bash\ncurl http://localhost:8080/blockchain/verify\n```\n\n## Project Structure\n\n```\ngo-voting-blockchain/\n├── cmd/\n│   └── api/\n│       └── main.go                    # Application entry point\n├── internal/\n│   ├── auth/                          # Authentication system\n│   │   ├── admin.go                   # Admin authentication\n│   │   └── jwt.go                     # JWT token management\n│   ├── blockchain/\n│   │   └── blockchain.go              # Core blockchain logic\n│   ├── crypto/\n│   │   └── crypto.go                  # Cryptographic operations\n│   ├── handlers/\n│   │   ├── auth.go                    # Authentication handlers\n│   │   └── handlers.go                # API request handlers\n│   ├── middleware/                    # Middleware components\n│   │   ├── auth.go                    # Authentication middleware\n│   │   ├── error.go                   # Error handling middleware\n│   │   ├── logging.go                 # Request logging middleware\n│   │   └── ratelimit.go               # Rate limiting middleware\n│   ├── models/\n│   │   └── models.go                  # Data models\n│   ├── persistence/\n│   │   └── persistence.go             # Database operations\n│   └── validation/\n│       └── validator.go               # Input validation\n├── tests/\n│   └── security_test.go               # Security integration tests\n├── scripts/\n│   ├── dev-setup.sh                   # Development setup script\n│   └── test-api.sh                    # API testing script\n├── .github/\n│   └── workflows/\n│       ├── ci.yml                     # Continuous integration\n│       └── development.yml            # Development workflow\n├── configs/\n├── Dockerfile                         # Docker configuration\n├── docker-compose.yml                 # Docker Compose setup\n├── railway.toml                       # Railway configuration\n├── config.development.env             # Development environment\n├── go.mod                             # Go modules\n├── go.sum                             # Module checksums\n├── README.md                          # Main documentation\n├── DEVELOPMENT.md                     # Development guide\n├── ROADMAP.md                         # Development roadmap\n├── CONTRIBUTING.md                    # Contribution guidelines\n├── PHASE1_TEST_REPORT.md              # Phase 1 test results\n└── LICENSE                            # MIT License\n```\n\n## Performance Optimization\n\n### For Railway Deployment\n\n1. **Database Indexing**: Automatic indexes on frequently queried fields\n2. **Redis Caching**: Optional caching layer for improved performance\n3. **Connection Pooling**: Optimized database connection management\n4. **Concurrent Mining**: Asynchronous block mining\n5. **Health Checks**: Automatic monitoring and restart policies\n\n### Scaling Considerations\n\n- **Horizontal Scaling**: Deploy multiple instances behind a load balancer\n- **Database Replication**: Use Railway's database scaling features\n- **CDN Integration**: Serve static content through Railway's CDN\n- **Auto-scaling**: Configure based on CPU/memory usage\n\n## 🔒 Security Features\n\n### Phase 1 Security Enhancements\n- **JWT Authentication**: Secure token-based authentication with refresh tokens\n- **Role-Based Access Control**: Admin and voter roles with proper permissions\n- **Rate Limiting**: Sliding window rate limiting with multiple tiers (strict, moderate, generous)\n- **Input Validation**: Comprehensive validation and sanitization of all inputs\n- **Error Handling**: Professional error handling with proper HTTP status codes\n- **Request Logging**: Complete API monitoring and audit logging\n- **Signature Verification**: Cryptographic proof of vote authenticity\n\n### Core Security Features\n- **RSA 2048-bit encryption** for digital signatures\n- **SHA-256 hashing** for block integrity\n- **Proof-of-Work** consensus mechanism\n- **CORS configuration** for API security\n- **Environment variable** management for secrets\n- **SQL injection prevention** with parameterized queries\n- **Private key ownership verification** for voter authentication\n\n### Security Testing\n- **Automated Security Tests**: Comprehensive test suite for all security features\n- **Integration Testing**: End-to-end testing of authentication flows\n- **Rate Limiting Tests**: Validation of rate limiting functionality\n- **Signature Verification Tests**: Cryptographic security validation\n\n## Monitoring\n\nRailway provides built-in monitoring for:\n- Application logs\n- Resource usage (CPU, Memory)\n- Request metrics\n- Error tracking\n- Health status\n\nAccess monitoring at: `https://railway.app/project/[project-id]/deployments`\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Port binding error**\n   - Railway automatically assigns PORT\n   - Don't hardcode port numbers\n\n2. **Database connection failed**\n   - Check DATABASE_URL is set\n   - Verify PostgreSQL service is running\n\n3. **Mining too slow**\n   - Adjust MINING_DIFFICULTY in environment\n   - Default is 3 for development\n\n4. **Memory issues**\n   - Increase Railway instance size\n   - Implement pagination for large datasets\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Contributors\n\nSee [CONTRIBUTORS.md](CONTRIBUTORS.md) for a list of all contributors.\n\n## License\n\nMIT License - see LICENSE file for details\n\n## 📞 Support\n\nFor issues and questions:\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/tolstoyjustin/go-voting-blockchain/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/tolstoyjustin/go-voting-blockchain/discussions)\n- 📧 **Contact**: tolstoyjustin@gmail.com\n- 🚂 **Railway Help**: [Railway Community](https://railway.app/help)\n\n## 🎯 Development Status\n\n### ✅ Phase 1: Security \u0026 Authentication (COMPLETED)\n- **JWT Authentication System** - Complete token-based authentication\n- **Role-Based Access Control** - Admin and voter roles with proper permissions\n- **Rate Limiting** - Sliding window rate limiting with multiple tiers\n- **Input Validation** - Comprehensive validation and sanitization\n- **Error Handling** - Professional error handling and recovery middleware\n- **Request Logging** - Complete API monitoring and logging system\n- **Security Tests** - Comprehensive automated security testing\n\n### 🔄 Phase 2: Data Persistence \u0026 Reliability (NEXT)\n- Database optimization and connection pooling\n- Data integrity and backup systems\n- Advanced persistence strategies\n- Performance monitoring and optimization\n\n### 📋 Future Phases\n- **Phase 3**: Performance Optimization\n- **Phase 4**: Advanced Features\n- **Phase 5**: User Experience Enhancement\n- **Phase 6**: Integration \u0026 APIs\n- **Phase 7**: Compliance \u0026 Auditing\n\nSee [ROADMAP.md](ROADMAP.md) for detailed development plans.\n\n## 🚀 Deployment Checklist\n\n### Pre-Deployment\n- [ ] Set up PostgreSQL database\n- [ ] Configure environment variables\n- [ ] Set appropriate mining difficulty\n- [ ] Configure JWT secret key\n- [ ] Set up Redis (optional, for caching)\n- [ ] Configure CORS for your frontend\n\n### Security Configuration\n- [ ] Change default admin password\n- [ ] Configure rate limiting thresholds\n- [ ] Set up proper logging levels\n- [ ] Configure error handling policies\n- [ ] Review authentication settings\n\n### Testing \u0026 Verification\n- [ ] Test all API endpoints\n- [ ] Verify authentication flows\n- [ ] Test rate limiting functionality\n- [ ] Verify blockchain persistence\n- [ ] Check health endpoint\n- [ ] Run security test suite\n- [ ] Validate signature verification\n\n### Deployment\n- [ ] Deploy to production environment\n- [ ] Verify all services are running\n- [ ] Monitor initial performance\n- [ ] Set up monitoring alerts\n- [ ] Document deployment configuration","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolstoyj%2Fgo-voting-blockchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftolstoyj%2Fgo-voting-blockchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolstoyj%2Fgo-voting-blockchain/lists"}