BharatChain is India's first comprehensive blockchain-powered digital governance platform that revolutionizes how citizens interact with government services. Built with cutting-edge technology, it provides:

• 🔐 Secure Document Management - Upload, verify, and store official documents on blockchain
• 📝 Smart Grievance System - AI-powered complaint processing with real-time tracking
• 👤 Digital Identity - Blockchain-based citizen registration and authentication
• 🤖 AI-Powered Analysis - Intelligent document verification and grievance categorization
• 🌐 Modern Web Interface - Beautiful, responsive Indian-themed user interface

Transform government services with transparency, security, and efficiency through blockchain technology.

Before starting, ensure you have:

• Windows 10/11 (our launcher is optimized for Windows)
• Node.js 18+ installed (Download here)
• Python 3.8+ installed (Download here)
• MetaMask Browser Extension (Install here)

Option 1: Simple Double-Click Launch

# Navigate to your BharatChain folder and double-click:
start.bat

Option 2: Enhanced Launcher

# Double-click for smart launcher with fallback:
bharatchain.bat

Option 3: PowerShell Advanced

# Right-click folder → "Open PowerShell here" → Run:
.\bharatchain.ps1

========================================
🇮🇳 BharatChain Launcher 🇮🇳
Starting all services...
========================================

✅ Stopping existing services...
🤖 Starting AI Service (Port 5001)...
⚙️ Starting Backend (Port 3001)...
🎨 Starting Frontend (Port 3000)...

========================================
🚀 All services are starting up!

Services run in separate windows.
Please wait 15-20 seconds for startup...

🌐 Your BharatChain will open at:
   http://localhost:3000

📡 Backend API available at:
   http://localhost:3001

🧠 AI Service available at:
   http://localhost:5001
========================================

🔥 Opening browser automatically...

After launch, you should see:

• 3 terminal windows opened (AI Service, Backend, Frontend)
• Browser opens automatically to http://localhost:3000
• Beautiful Indian-themed interface loads
• "Connect MetaMask" button appears on the homepage

# Method 1: Close terminal windows manually
# Method 2: Use stop command
bharatchain.bat stop

# Method 3: Kill all Node.js processes
taskkill /f /im node.exe
taskkill /f /im python.exe

1. Install MetaMask browser extension if not already installed
2. Create/Import wallet and set up your account
3. Visit http://localhost:3000
4. Click "Connect MetaMask" on the homepage
5. Approve connection in MetaMask popup
6. Sign message to authenticate (no gas fees!)

1. After wallet connection, you'll see the registration form
2. Fill required details:
   • Full Name
   • Aadhar Number (12 digits)
   • Phone Number
   • Email Address
   • Date of Birth
3. Submit registration - your identity gets stored on blockchain
4. Success! You're now a registered BharatChain citizen

Upload Documents:

1. Navigate to "Documents" in the dashboard
2. Click "Upload Document"
3. Select file (PDF, JPG, PNG - max 10MB)
4. Choose document type (Aadhar, PAN, etc.)
5. Wait for AI processing - automatic text extraction & verification
6. Document stored on blockchain with IPFS hash

View Documents:

• Dashboard overview shows all your documents
• Click any document to view details
• Verification status shown (Pending/Verified/Rejected)
• Download original or processed version

File a Complaint:

1. Go to "Grievances" section
2. Click "Submit New Grievance"
3. Fill the form:
   • Subject: Brief description
   • Description: Detailed explanation
   • Category: Select appropriate category
   • Urgency: Select priority level
4. Submit - AI automatically analyzes and categorizes
5. Track status - real-time updates on progress

AI Analysis Features:

• Sentiment Analysis: Detects urgency and emotion
• Smart Categorization: Auto-assigns to correct department
• Priority Scoring: Urgent issues get higher priority
• Response Time: Estimated resolution timeline

Your dashboard shows:

• Document Summary: Total uploaded, verified, pending
• Grievance Status: Active, resolved, in-progress
• Recent Activity: Latest actions and updates
• Quick Actions: Fast access to common tasks
• Notifications: Important updates and alerts

If you want to run services individually for development:

Install Dependencies:

# Clone repository
git clone https://github.com/your-username/WHCL-Hackathon.git
cd WHCL-Hackathon

# Install backend dependencies
cd server && npm install

# Install frontend dependencies  
cd ../client && npm install

# Install AI service dependencies
cd ../ai-service && pip install -r requirements.txt

Start Services Manually:

# Terminal 1: AI Service
cd ai-service
python simple_app.py

# Terminal 2: Backend
cd server
npm start

# Terminal 3: Frontend
cd client
npm start

WHCL-Hackathon/
├── 🎨 client/                 # React frontend
│   ├── src/components/        # UI components
│   ├── src/context/          # Web3 & app context
│   └── public/               # Static assets
├── ⚙️ server/                 # Node.js backend  
│   ├── routes/               # API endpoints
│   ├── database/             # DB models & config
│   └── server.js             # Main server file
├── 🤖 ai-service/             # Python AI service
│   ├── simple_app.py         # Flask app
│   └── requirements.txt      # Python dependencies
├── 🔗 contracts/             # Smart contracts
│   ├── CitizenRegistry.sol   # Citizen management
│   ├── DocumentRegistry.sol  # Document storage
│   └── GrievanceSystem.sol   # Grievance handling
├── 🚀 Launchers/             # One-click launch files
│   ├── start.bat             # Simple launcher
│   ├── bharatchain.bat       # Enhanced launcher
│   └── bharatchain.ps1       # PowerShell launcher
└── 📚 docs/                  # Documentation

Problem: "Port already in use" or services fail to start

Solutions:

# Kill existing processes
taskkill /f /im node.exe
taskkill /f /im python.exe

# Then restart
.\start.bat

Problem: "Module not found" errors

Solutions:

# Reinstall dependencies
cd server && npm install
cd ../client && npm install
cd ../ai-service && pip install -r requirements.txt

Problem: MetaMask doesn't connect or shows errors

Solutions:

• Check MetaMask is unlocked and account is selected
• Refresh the page (Ctrl+F5) and try again
• Switch to correct network (use local network for development)
• Clear browser cache and restart browser

Problem: AI analysis fails or returns errors

Solutions:

# Check if Python dependencies are installed
cd ai-service
pip install -r requirements.txt

# Check if service is running
curl http://localhost:5001/health

# Restart AI service
python simple_app.py

Problem: React app shows blank page or errors

Solutions:

# Clear React cache and restart
cd client
npm start -- --reset-cache

# Or delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm start

Problem: "Database locked" or connection errors

Solutions:

# Stop all services first
taskkill /f /im node.exe

# Delete database lock file
del server\database\*.db-wal
del server\database\*.db-shm

# Restart backend
cd server && npm start

# Quick status check
bharatchain.bat status

# Manual health checks
curl http://localhost:3000    # Frontend
curl http://localhost:3001/api/health    # Backend  
curl http://localhost:5001/health        # AI Service

• Frontend: Check browser console (F12 → Console)
• Backend: Look at terminal running npm start in server folder
• AI Service: Check terminal running python simple_app.py

If you're still having issues:

1. Check all services are running: Use bharatchain.bat status
2. Review terminal outputs: Look for error messages in service windows
3. Try clean restart: Stop all services, wait 5 seconds, restart
4. Check prerequisites: Ensure Node.js, Python, and MetaMask are installed
5. Create GitHub issue: If problem persists, report it with error details

• First startup takes 20-30 seconds - be patient!
• Keep terminal windows open - closing them stops services
• Use Chrome/Edge browsers - better MetaMask compatibility
• Clear browser cache periodically - prevents stale data issues
• Restart services daily - keeps everything fresh during development

Create .env file in server folder:

# Database
DATABASE_URL=sqlite:./database/bharatchain.db
NODE_ENV=development

# Security
JWT_SECRET=your-super-secret-jwt-key-here
SESSION_SECRET=your-session-secret-here

# Services
FRONTEND_URL=http://localhost:3000
AI_SERVICE_URL=http://localhost:5001

# Blockchain (for production)
MUMBAI_RPC_URL=https://rpc-mumbai.maticvigil.com
PRIVATE_KEY=your-wallet-private-key-for-deployment

cd client
npm run build
# Deploy dist/ folder to your hosting service

cd server
# Configure environment variables on hosting platform
# Deploy server folder

cd ai-service
# Install requirements: pip install -r requirements.txt
# Start with: python simple_app.py

We welcome contributions! Here's how to get started:

1. Fork the repository on GitHub
2. Clone your fork: git clone https://github.com/your-username/WHCL-Hackathon.git
3. Create feature branch: git checkout -b feature/amazing-feature
4. Make changes and test thoroughly
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open Pull Request

• Write tests for new features
• Follow existing code style
• Update documentation for API changes
• Test on Windows (our primary platform)
• Include screenshots for UI changes

# Run all tests
npm test                    # Backend tests
cd client && npm test       # Frontend tests  
cd ai-service && python -m pytest  # AI service tests

# Manual testing
.\start.bat                 # Test launcher
bharatchain.bat status      # Test status check

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

• Government of India - Digital India Initiative inspiration
• Ethereum Foundation - Blockchain infrastructure
• OpenZeppelin - Smart contract security standards
• Material-UI Team - Beautiful React component library
• MetaMask Team - Web3 wallet integration
• Flask & React Communities - Excellent documentation and support

• Digital India 🇮🇳
• Transparent Governance 🏛️
• Citizen Empowerment 👥
• Blockchain Innovation ⛓️

• 📧 Email: [email protected]
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📚 Documentation: Complete user manual above
• 🚀 Quick Start: Just run start.bat or bharatchain.bat

Happy coding! 🎉 Let's build the future of digital governance together! 🇮🇳