Votely - Blockchain-Powered Voting Platform

Secure, Transparent, Tamper-Proof Elections

---

🗳️ About Votely

Votely is a modern, blockchain-powered voting platform designed for educational institutions across India. It provides a secure, transparent, and tamper-proof election system for schools, colleges, and universities.

Key Features

• 🔐 Blockchain Security - Votes recorded on Ethereum blockchain for immutability
• 🎓 Multi-Institution Support - Handle elections for multiple schools and colleges
• 👛 MetaMask Integration - Secure wallet-based voter authentication
• 📊 Real-Time Results - Live vote counting with beautiful visualizations
• 🌙 Dark/Light Mode - Beautiful UI with theme support
• 📱 Responsive Design - Works seamlessly on desktop and mobile

---

📁 Project Structure

votely/
├── 📂 src/                     # Frontend Application (React + TypeScript)
│   ├── components/             # Reusable UI components
│   │   ├── ui/                 # shadcn/ui component library
│   │   ├── Header.tsx          # Navigation header
│   │   ├── CandidateCard.tsx   # Candidate display component
│   │   └── ResultsChart.tsx    # Vote visualization charts
│   ├── contexts/               # React Context providers
│   │   ├── AuthContext.tsx     # Authentication state
│   │   ├── ElectionContext.tsx # Election data & voting logic
│   │   ├── ThemeContext.tsx    # Theme management
│   │   └── WalletContext.tsx   # MetaMask wallet integration
│   ├── pages/                  # Application pages
│   │   ├── Home.tsx            # Landing page
│   │   ├── VotePage.tsx        # Voting interface
│   │   ├── ResultsPage.tsx     # Election results
│   │   └── AuthPage.tsx        # Login/Signup
│   ├── hooks/                  # Custom React hooks
│   ├── integrations/           # Third-party integrations
│   │   └── supabase/           # Supabase client & types
│   └── lib/                    # Utility functions
│
├── 📂 contracts/               # Smart Contracts (Solidity)
│   └── ChainVote.sol           # Main voting contract
│
├── 📂 scripts/                 # Deployment Scripts
│   └── deploy.js               # Hardhat deployment script
│
├── 📂 supabase/                # Backend Configuration
│   └── config.toml             # Supabase configuration
│
├── 📂 public/                  # Static Assets
│   ├── favicon.ico
│   └── robots.txt
│
└── 📄 Configuration Files
    ├── hardhat.config.js       # Hardhat (Ethereum) configuration
    ├── vite.config.ts          # Vite bundler configuration
    ├── tailwind.config.ts      # Tailwind CSS configuration
    └── tsconfig.json           # TypeScript configuration

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• Bun or npm
• MetaMask browser extension
• Git

Installation

1. Clone the repository

   git clone https://github.com/yourusername/votely.git
   cd votely

2. Install dependencies

   bun install
   # or
   npm install

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration (see Environment Variables)

4. Start development server

   bun run dev
   # or
   npm run dev

5. Open in browser

   http://localhost:5173
   

---

⛓️ Smart Contract Deployment

Local Development (Hardhat)

1. Start local blockchain

   npx hardhat node

2. Deploy contract

   npx hardhat run scripts/deploy.js --network localhost

3. Update .env with the deployed contract address

   VITE_CONTRACT_ADDRESS=0x...

4. Configure MetaMask

   • Add network with RPC URL: http://127.0.0.1:8545
   • Chain ID: 31337
   • Import test account using Hardhat private key

Testnet Deployment (Sepolia)

1. Get Sepolia ETH from a faucet

2. Configure deployment (⚠️ Never commit real private keys!)

   • Use environment variables or secure key management
   • See .env.example for required variables

3. Deploy to Sepolia

   npx hardhat run scripts/deploy.js --network sepolia

---

🔐 Environment Variables

Variable	Description	Required
VITE_CONTRACT_ADDRESS	Deployed ChainVote contract address	Yes
VITE_RPC_URL	Ethereum RPC URL (default: localhost:8545)	No
VITE_SUPABASE_URL	Supabase project URL	Auto
VITE_SUPABASE_PUBLISHABLE_KEY	Supabase anon key	Auto

⚠️ Security Warning: Never commit .env files with real private keys or secrets!

---

🛠️ Tech Stack

Frontend

Technology	Purpose
React 18	UI library
TypeScript	Type safety
Vite	Build tool & dev server
Tailwind CSS	Utility-first styling
shadcn/ui	Component library
React Router	Client-side routing
Recharts	Data visualization

Backend

Technology	Purpose
Supabase	Authentication & Database
Edge Functions	Serverless backend logic

Blockchain

Technology	Purpose
Solidity	Smart contract language
Hardhat	Ethereum development environment
MetaMask	Wallet integration

---

📜 Smart Contract API

ChainVote.sol

Function	Description	Access
startElection(name, candidates[])	Start a new election	Admin
vote(candidateId)	Cast a vote	Voter
endElection()	End the active election	Admin
getCandidates()	Get all candidates	Public
getResults()	Get election results	Public
checkVoterStatus(address)	Check if address has voted	Public

---

🧪 Testing

# Run frontend tests
bun run test

# Run smart contract tests
npx hardhat test

---

📦 Building for Production

# Build frontend
bun run build

# Preview production build
bun run preview

---

🤝 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.

---

Made with ❤️ for Indian Educational Institutions

Getting Started • Deploy Contract • Contributing