ElectIQ — India's Interactive Election Education Platform

"The world's largest democracy begins with you."

PromptWars: Virtual — Build with AI, Challenge 2 Vertical: Election Process Education Assistant

---

📖 Project Overview

ElectIQ is a production-ready, dual-mode interactive election education platform built for Indian voters — especially first-time voters. It combines visual exploration with structured learning and AI-powered assessment, all wrapped in a vintage civic handbook aesthetic that honours the weight and history of Indian democracy.

The Two Modes

Mode	Description
The Flow Map	Visual node-based flowchart of the complete Indian election lifecycle (7 stages). Every node is clickable — opens a rich dossier side panel with pre-written accurate content, a timeline marker, and an inline Gemini AI chat scoped to that stage.
Learn & Quiz	A structured 7-module lesson journey with progress saved to Firestore. After each module, Gemini generates a fresh 4-question quiz. Final reward: a personalised Voter Readiness Certificate generated by Gemini and downloadable as PDF.

---

🛠️ Google Services Used

Service	How It's Used
Google Gemini API (gemini-1.5-flash)	Flowmap per-stage AI chat, dynamic quiz generation (4 MCQs per module), score encouragement messages, personalised voter checklist
Firebase Authentication	Google Sign-In (OAuth popup) and Email/Password auth — no anonymous sessions
Firebase Hosting	Static site deployment with security headers and CDN
Firebase Firestore	Persists user progress (completed modules, quiz scores, explored stages) per authenticated UID
Google Fonts	Playfair Display, Crimson Pro, Hind, IM Fell English — all loaded with font-display: swap
Google Translate Widget	All 22 scheduled Indian languages accessible from the header
Google Analytics 4	Page views, user sessions, quiz interactions tracked

---

🏗️ Architecture

ElectIQ/
├── index.html          ← Landing page (public) — smart CTA swap for signed-in users
├── login.html          ← Auth gate — Google Sign-In + Email/Password
├── flowmap.html        ← Interactive election lifecycle flowchart (protected)
├── learn.html          ← 7-module lesson journey (protected)
├── quiz.html           ← Gemini-generated MCQ quiz (protected)
├── checklist.html      ← Personalised Voter Readiness Certificate (protected)
├── css/
│   ├── base.css        ← Design system: all CSS variables, resets, shared components
│   ├── landing.css     ← Landing page specific styles
│   ├── auth.css        ← Login card, Google button, form fields, avatar dropdown
│   ├── flowmap.css     ← Flowchart, node cards, dossier side panel, Gemini chat
│   ├── learn.css       ← Lesson card, progress bar with tally marks
│   ├── quiz.css        ← MCQ answer sheets, correct/wrong stamps, score card
│   └── checklist.css   ← Gazette document style, print stylesheet
├── js/
│   ├── config.js       ← GITIGNORED: Firebase + Gemini credentials (copy from config.example.js)
│   ├── config.example.js ← Safe template — commit this, not config.js
│   ├── auth.js         ← Firebase Auth: Google sign-in, email/password, sign-out, auth guard
│   ├── header.js       ← Auth guard runner + user avatar dropdown for protected pages
│   ├── gemini.js       ← Gemini REST API wrapper: sanitization, debounce, caching, JSON parsing
│   ├── firebase.js     ← Firestore progress tracker using authenticated UID
│   ├── flowmap.js      ← Stage data, node rendering, dossier logic, Gemini chat
│   ├── learn.js        ← 7 lesson modules, progress bar, Firebase save/restore
│   ├── quiz.js         ← Quiz generation, MCQ rendering, answer feedback, score summary
│   ├── checklist.js    ← Checklist generation, phase grouping, print, Web Share API
│   └── translate.js    ← Google Translate widget init
├── assets/icons/       ← SVG line-art icons for each of the 7 election stages
├── .gitignore          ← Excludes js/config.js and other non-committed files
├── firebase.json       ← Firebase Hosting config with security headers
└── README.md

---

⚙️ How the Solution Works

Flow Map

1. User opens flowmap.html — the flowmap.js module renders 7 node cards in three colour-coded phase groups (Pre-Election in Saffron, Election Day in Green, Post-Election in Navy)
2. Clicking a node slides in a manila folder dossier panel from the right
3. The dossier shows 3–4 paragraphs of pre-written, ECI-accurate content + a timeline marker
4. The "ASK GEMINI →" rubber stamp button opens an inline chat panel scoped to that stage
5. Chat history is maintained per stage within the session
6. Explored stages get a green ink checkmark stamp; state persists via Firestore

Learn & Quiz

1. User opens learn.html — progress is restored from Firestore on returning visits
2. One lesson module at a time, displayed in a khadi white card with ruled-line texture
3. "Next Module →" advances and saves progress; "Test Me on This" links to the quiz
4. quiz.html?module=N calls Gemini to generate 4 MCQs for that module (cached in sessionStorage)
5. Users select answers, submit per question, receive immediate correct/wrong stamp feedback
6. After all 4 questions, a score summary card appears with a Gemini-generated encouragement message
7. After all 7 modules, the user is directed to checklist.html
8. Gemini generates a personalised 8–10 item voter checklist grouped by phase (Before/During/After)
9. Users can tick off items, download as PDF via window.print(), or share via the Web Share API

---

💻 Local Setup

Prerequisites

• A modern web browser (Chrome, Firefox, Safari, Edge)
• A text editor
• Internet access (for Google Fonts, Firebase SDK, Gemini API)

Steps

1. Clone the repository

   git clone https://github.com/Atrijaa-Biswas/electiq.git
   cd electiq

2. Create your config file

   cp js/config.example.js js/config.js

3. Fill in your credentials in js/config.js:

   • Gemini API key: Get from Google AI Studio
   • Firebase config: Create a project at Firebase Console, enable Hosting, Firestore (in production mode), and Anonymous Auth. Copy the Web App config object.
   • GA4 Measurement ID: Optional — create a GA4 property at analytics.google.com

4. Open locally

   The simplest way is to use the VS Code Live Server extension, or any static file server:

   # Python
   python -m http.server 8080
   
   # Node
   npx serve .

   Then open http://localhost:8080 in your browser.

   Note: file:// protocol won't work for the Firebase SDK module imports. You must use a local HTTP server.

---

🚀 Firebase Hosting Deployment

1. Install Firebase CLI

   npm install -g firebase-tools

2. Login

   firebase login

3. Initialize project (first time only)

   firebase init hosting
   # Choose your Firebase project
   # Set public directory to: .
   # Configure as single-page app: No

4. Deploy

   firebase deploy --only hosting

5. Firestore Security Rules — in Firebase Console → Firestore → Rules, set:

   rules_version = '2';
   service cloud.firestore {
     match /databases/{database}/documents {
       match /users/{userId} {
         allow read, write: if request.auth != null && request.auth.uid == userId;
       }
     }
   }

---

🔒 Authentication

Why Proper Auth (not anonymous sessions)

ElectIQ uses Firebase Authentication with real user accounts rather than anonymous sessions. This means:

• Progress is tied to a real identity and persists across browsers and devices
• Firestore security rules can enforce strict per-user data isolation
• Users can sign in with their Google account (one tap) or email/password
• All quiz scores, explored stages, and lesson progress belong to the user's UID, not a transient session token

Enabling Sign-in Providers in Firebase Console

1. Go to Firebase Console → Authentication → Sign-in method
2. Enable Google — set a project support email
3. Enable Email/Password
4. Do NOT enable Anonymous, Phone, or any other provider

How Route Protection Works

Each protected page (flowmap.html, learn.html, quiz.html, checklist.html) starts with body { opacity: 0 }. The page JS calls HeaderController.init() before any rendering. This internally calls onAuthStateChanged from Firebase Auth:

• If the user is signed in → body is revealed, user avatar is rendered in the header
• If not signed in → browser immediately redirects to login.html before the user can see any content

This prevents any flash of protected content before redirect.

Firestore Security Rules

Paste these exact rules in Firebase Console → Firestore → Rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId}/{document=**} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }
  }
}

This means:

• Unauthenticated requests are denied entirely
• Each signed-in user can only read and write documents under their own UID path
• No user can access another user's progress data

---

🛡️ Security Notes

• js/config.js is listed in .gitignore — never commit it
• All user input is sanitized (HTML stripped, 500-char limit) before reaching Gemini
• Display names are sanitized (HTML stripped, max 50 chars) before being stored in Firebase Auth profile
• Content Security Policy meta tags on every HTML page restrict scripts to trusted Google domains
• Firestore rules restrict each user to their own document path
• Firebase SDK manages ID tokens internally — tokens are never manually stored or exposed
• All external resources loaded over HTTPS

---

🤔 Assumptions Made

1. Users have modern browsers (ES6+ module support)
2. Gemini API key has sufficient quota for quiz/chat usage
3. Firebase project has Firestore, Google Sign-In, Email/Password Auth, and Hosting enabled
4. The platform is designed for educational use — content accuracy is based on ECI public documentation as of 2024
5. The Google Translate widget is sufficient for multilingual support (no custom translation API calls)
6. window.print() PDF generation is acceptable — no server-side PDF library required
7. Google Sign-In popup works in the deployment environment (popups must not be blocked)

---

🎨 Design Philosophy

The UI aesthetic is inspired by post-independence Indian civic documents — aged parchment backgrounds, sepia ink borders, Playfair Display headlines, and Ashoka Chakra watermarks. All animations are slow and deliberate (no flashy effects). The design passes WCAG AA contrast requirements and is fully keyboard navigable.

---

📜 License

MIT License — see LICENSE for details.

---

Built for PromptWars: Virtual — Build with AI, Challenge 2. ElectIQ is an independent civic education tool and is not affiliated with the Election Commission of India.