🗳️ Matdata Mitra — मतदाता मित्र

India's Most Inclusive Election Education Assistant

Built for Virtual Prompt War Challenge 2

---

🇮🇳 The Problem

India has 96 crore+ registered voters — but existing election tools fail most of them.

Who gets left behind	Why
👴 Senior citizens (60+)	No smartphone, Hindi needed, large text required
🧑 First-time voters (18-21)	Lowest turnout nationally — feel embarrassed to ask
♿ 8.6 crore PwD voters	Saksham app barely anyone knows exists
🌐 Non-Hindi/English speakers	ECI website mostly in two languages
📵 Rural voters	45% of India has limited internet

Most election apps assume everyone is the same type of voter. India's voters are NOT.

---

💡 The Solution

Matdata Mitra (Voter's Friend) — one app, two complete experiences:

🧑 Young Voter Mode

For first-time voters aged 18-35 with smartphones.

• 💬 AI Chat — Ask anything about elections in your language (Google Gemini)
• 🧠 Gamified Quiz — 8 questions, XP points, badge unlocks
• 📍 Polling Booth Finder — GPS-based using free OpenStreetMap
• ✅ EVM Fact Checker — Bust myths with verified ECI data
• 📅 Election Timeline — 8 step-by-step voting guide
• 🗳️ Impact Calculator — See how close elections have been in your constituency
• 🌟 Share Card — Generate your "I'm Voting!" card

👴 Elder-Friendly Mode

For senior citizens, differently-abled voters, and first-time computer users.

• 🔊 Voice Navigation — Full TTS reads every section aloud
• 🎤 Voice Input — Ask questions by speaking (no typing needed)
• 📝 Hindi First — All content in Hindi with English below
• 🖼️ Giant Buttons — Minimum 72px height, impossible to miss
• 🖨️ Printable Voter Guide — Personalised guide for election day
• 📞 Emergency Helpline — One-tap 1950 button always visible
• 🏛️ CSC Locator — Find nearest Common Service Centre

---

🔴 Real Problems We Solve

❌ Existing problem          ✅ Our solution
─────────────────────────────────────────────────────────
Voter Helpline 1950          → AI chat (no wait time)
  has long wait times

ECI website confusing UI     → Simple step-by-step guide
                               in user's language

EVMs "rigged" WhatsApp       → Gemini-powered fact checker
  misinformation               with ECI verified data

Elderly can't find booth     → GPS + pincode booth finder
                               + printable guide

No internet on election day  → Printable voter kit
                               with all details

PwD voters don't know        → Dedicated elder mode
  their rights                 + postal ballot info

22 official languages        → Google Translate widget
  underserved                  + 10 Indian languages

---

🛠️ Tech Stack

Google Services (Judges Criteria)

Service	Usage
Google Gemini 2.0 Flash	AI chat, fact checking, quiz generation
Firebase Authentication	Google Sign-In
Firebase Firestore	User progress, chat history, XP sync
Firebase Analytics	Track learning behavior
Google Translate Widget	10 Indian languages
Google Cloud Run	Deployment and hosting
Web Speech API	Voice input + Text-to-Speech (browser built-in)

Free Map Stack (Zero Cost)

Service	Usage
Leaflet.js	Interactive map display
OpenStreetMap	Free map tiles
Nominatim	Pincode → GPS coordinates
Overpass API	Find nearby govt buildings
OSRM	Route directions

Backend

• Node.js + Express — Secure API proxy
• Helmet — Security headers
• express-rate-limit — Abuse prevention
• dotenv — Environment variable management

---

🔐 Security Architecture

BEFORE (insecure):
Browser ──────────────────────────► Gemini API
        (API key visible in DevTools)

AFTER (secure):
Browser ──► server.js ──► Gemini API
            (API key        (key never
             server-only)    reaches browser)

• ✅ Zero API keys in client-side code
• ✅ All secrets in environment variables
• ✅ Server-side input sanitization (second layer)
• ✅ Rate limiting on all /api/* endpoints
• ✅ Helmet security headers
• ✅ .env blocked by .gitignore

---

📁 Project Structure

matdata-mitra/
├── server.js               ← Express server (security backbone)
├── package.json
├── Dockerfile              ← Google Cloud Run deployment
├── .env                    ← secrets (never committed)
├── .env.example            ← template for setup
├── .gitignore
│
├── index.html              ← Landing page (persona selector)
├── young-voter.html        ← First-time voter experience
├── elder-voter.html        ← Elder + accessible experience
│
├── css/
│   ├── main.css            ← Shared foundation styles
│   ├── young.css           ← Modern gamified theme
│   └── elder.css           ← Large text, high contrast theme
│
└── js/
    ├── app.js              ← Core logic, quiz, TTS, voice
    ├── gemini.js           ← AI client (calls /api/*)
    ├── firebase.js         ← Auth + Firestore + Analytics
    └── maps.js             ← Leaflet + free map services

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Google AI Studio account (free Gemini API key)
• Firebase project (free Spark plan)

1. Clone the repository

git clone https://github.com/yourusername/matdata-mitra.git
cd matdata-mitra

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env

Edit .env with your real values:

GEMINI_API_KEY=your_gemini_key_from_aistudio
FIREBASE_API_KEY=your_firebase_api_key
FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_STORAGE_BUCKET=your_project.appspot.com
FIREBASE_MESSAGING_SENDER_ID=your_sender_id
FIREBASE_APP_ID=your_app_id
FIREBASE_MEASUREMENT_ID=G-your_measurement_id
PORT=8080
NODE_ENV=development

4. Get your API keys

Gemini API Key (Free): → aistudio.google.com → Get API Key → Create API Key

Firebase Config: → console.firebase.google.com → Add project → Authentication → Enable Google Sign-In → Firestore → Create database (test mode) → Project Settings → Your Apps → Web App → Copy config

5. Run locally

npm run dev

Open http://localhost:8080 🎉

6. Test the API

# Health check
curl http://localhost:8080/api/health

# Should return:
# {"status":"healthy","gemini":true,"firebase":true,...}

---

☁️ Deploy to Google Cloud Run

# Build and push Docker image
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/matdata-mitra

# Deploy to Cloud Run
gcloud run deploy matdata-mitra \
  --image gcr.io/YOUR_PROJECT_ID/matdata-mitra \
  --platform managed \
  --region asia-south1 \
  --allow-unauthenticated \
  --set-env-vars GEMINI_API_KEY=your_key,\
                 FIREBASE_PROJECT_ID=your_project,\
                 NODE_ENV=production

---

♿ Accessibility Features

Feature	Implementation
Skip navigation link	Keyboard users jump to main content
ARIA labels	Every interactive element labelled
High contrast mode	WCAG AAA compliant
Large font mode	100% → 160% adjustable
Screen reader support	All sections have role + aria-labelledby
Keyboard navigation	Full tab order, focus-visible rings
Reduced motion	Respects OS prefers-reduced-motion
Voice navigation	Full TTS for elder mode
Voice input	Speech recognition for all inputs
Print styles	Voter guide printable without internet
Minimum touch targets	48×48px (elder buttons: 72px+)

---

🌐 Supported Languages

हिंदी · English · বাংলা · తెలుగు · मराठी · தமிழ் · ગુજરાતી · ಕನ್ನಡ · ਪੰਜਾਬੀ · മലയാളം

---

📊 Judging Criteria Coverage

Criteria	Implementation
Code Quality	Modular JS, JSDoc, 'use strict', consistent naming
Security	Server-side keys, Helmet, rate limiting, input sanitization, XSS prevention
Efficiency	Lazy loading, debounced handlers, capped history, free APIs
Testing	Pure functions, error boundaries, graceful degradation
Accessibility	ARIA, skip links, voice, contrast, large text, print, reduced motion
Google Services	Gemini + Firebase Auth + Firestore + Analytics + Translate + Cloud Run

---

🙏 Important Contacts (Built Into the App)

📞 Voter Helpline: 1950 (Toll-free, 24/7)
🌐 ECI Website: eci.gov.in
🗳️ Voter Registration: voters.eci.gov.in
📍 Booth Search: electoralsearch.eci.gov.in
♿ PwD Assistance: saksham.eci.gov.in
📸 Report Violations: cVIGIL App
🏛️ CSC Locator: locator.csccloud.in

---

📄 License

MIT © 2025 Matdata Mitra

---

⚠️ Disclaimer

This is an educational tool built for a hackathon challenge. For official election information, always visit eci.gov.in or call the Voter Helpline at 1950.

---

Built with ❤️ for Indian Democracy

Jai Hind 🇮🇳