# Sunrise Voting Station — Complete User Guide
**For School Staff · Election Officers · Principal · Teachers**

> **A note on screenshots:** Screenshot placeholder boxes (📷 SCREENSHOT) are positioned throughout this guide with detailed descriptions of what each screen looks like. To add actual images, capture each described screen and save under `screenshots/` folder with the suggested filename — they'll automatically render here.

---

## 📑 Table of Contents

1. [System Overview](#1-system-overview)
2. [Two Modes Explained](#2-two-modes-explained)
3. [Quick Start — One Booth Election](#3-quick-start--one-booth-election)
4. [Detailed Setup (Institution Mode)](#4-detailed-setup-institution-mode)
5. [Running the Election Day](#5-running-the-election-day)
6. [End of Day — Closing & Results](#6-end-of-day--closing--results)
7. [Multi-Booth Election (650+ voters)](#7-multi-booth-election)
8. [Cloud Sync & Live Dashboard](#8-cloud-sync--live-dashboard-optional)
9. [Print Kit — Paper Backup Materials](#9-print-kit--paper-materials)
10. [Guest Mode for Students](#10-guest-mode-for-students)
11. [AI Features (Gemini)](#11-ai-features-gemini)
12. [Troubleshooting](#12-troubleshooting)
13. [Roles & Responsibilities](#13-roles--responsibilities)
14. [Glossary](#14-glossary)

---

## 1. System Overview

The Sunrise Voting Station is a complete **digital polling system** for school elections. It mirrors the real Election Commission of India (ECI) Electronic Voting Machine (EVM) experience.

### What it does
- ✅ Conducts real elections with persistent records
- ✅ Allows multiple booths to run in parallel and combine results
- ✅ Generates official winner certificates with school branding
- ✅ Provides educational demo mode for students
- ✅ Prints all paper materials (ballots, voter rolls, tally sheets)

### Where to find it
**File path:** `D:\WebDev_2\Sunrise Education Academy\voting-station\index.html`

Double-click `index.html` to open in any modern browser (Chrome / Edge / Firefox recommended).

### What devices work
- ✅ Windows / Mac laptops
- ✅ Android tablets / phones
- ✅ iPads
- ❌ Internet Explorer (won't work — too old)

---

## 2. Two Modes Explained

When you open the voting station, you'll see a **landing screen** with two big options:

> 📷 **SCREENSHOT [01-landing.png]** *Suggested capture: the landing page showing two cards side-by-side*
>
> **What you should see:**
> - A dark navy header with the Sunrise logo (golden halo around it, sparkle stars)
> - Title: "🗳️ Voting Station"
> - Two large buttons below:
>   - **LEFT (green border):** 🎓 Guest Mode — "No login needed"
>   - **RIGHT (orange border):** 🏛️ Institution Mode — "Admin password required"

### Mode 1 — 🎓 Guest Mode (no login)
For visitors, students, exploring the system, or educational demos.
- Pre-built sample elections (Lok Sabha, Vidhan Sabha, Panchayat, Best Pet, etc.)
- Data **not saved** — fresh start every visit
- Tab close = data wiped
- Cannot affect real election data

### Mode 2 — 🏛️ Institution Mode (admin password)
For real school elections.
- Full features: voter rolls, multi-booth, cloud sync, certificates, archive
- Persistent records — survives refresh, tab close, power cut
- Admin password required to enter and to perform admin actions
- **This is what you use on Election Day.**

### Default admin password
> ⚠️ **`sunrise2026`** — change it on first login (see [Section 4](#4-detailed-setup-institution-mode))

---

## 3. Quick Start — One Booth Election

If you have a small election (50-150 voters, 1 device, no internet needed), follow this 5-step quick start:

### Step 1 — Open the app
Double-click `voting-station/index.html` → choose **🏛️ Institution Mode** → enter password `sunrise2026`.

### Step 2 — Configure election
Fill in:
- **Election Title:** e.g., "School Captain Election 2026-27"
- **Position:** e.g., "School Captain"
- **Election Date:** today's date

### Step 3 — Add candidates
The system pre-loads **Group A — Pen 🖊️** vs **Group B — Book 📖** + NOTA. Edit names/symbols if needed, or click **"+ Add Group"** for more.

### Step 4 — Add voters
In the **Voter Roll** card, paste names into the text box (one per line):
```
Ravi Kumar, 9A
Priya Sharma, 9A
Anil Singh, 10B
...
```
Click **⊕ Add from Paste**.

### Step 5 — Start voting
Click the orange **🚀 Start Voting Now →** button. Done!

Now teachers operate the system at the booth (see [Section 5](#5-running-the-election-day)).

---

## 4. Detailed Setup (Institution Mode)

### 4.1 First-time login

When you click **Institution Mode** for the first time:

> 📷 **SCREENSHOT [02-password-prompt.png]** *Suggested capture: the password modal*
>
> **What you should see:** A small white modal in the center with title "🔑 Admin Password Required" and a password input field. Two buttons at bottom: "Cancel" and "Verify".

Type `sunrise2026` (default) and click **Verify**.

### 4.2 Change the default password (recommended)

After logging in, scroll to **Election Configuration** card. Click **🔑 Change Password** in the top-right corner.

> 📷 **SCREENSHOT [03-change-password.png]** *Suggested capture: change-password modal*
>
> **What you should see:** Two password fields — "New password" and "Confirm new password". Enter at least 4 characters. Both must match.

> ⚠️ **Save the new password somewhere safe** — there's no recovery if forgotten. If lost, you'd need to clear the browser's localStorage (which wipes all election data).

### 4.3 Configure election details

> 📷 **SCREENSHOT [04-setup-screen.png]** *Suggested capture: the full Setup screen showing all cards*
>
> **What you should see:**
> - Top: Hero bar with election title pill
> - Tab navigation: 1. Setup (active) · 2. Voting · 3. Results
> - Cards going down:
>   - Multi-booth Quickstart (collapsible details)
>   - **Election Configuration** — title, position, date, VVPAT duration, auto-backup
>   - **Booth Identity** — booth ID + label
>   - **Candidates / Groups** — list with edit, symbol picker, add/remove
>   - **Voter Roll** — bulk paste, CSV upload, voter list grid
>   - **Cloud Sync · Live Dashboard** (optional)
>   - **Start Election** — orange button at bottom

### 4.4 Election Type — Group vs Candidate

In the **Election Configuration** card, choose the type:

> 📷 **SCREENSHOT [05-election-type-toggle.png]** *Suggested capture: the type toggle showing both options*
>
> **What you should see:** Two side-by-side buttons:
> - **🖊️📖 Group / Party** — Two parties (e.g., Pen vs Book)
> - **👤 Individual Candidates** — Vote for individual people by name

| When to use Group | When to use Individual |
|---|---|
| Houses competing (Pen vs Book) | Head Boy / Head Girl election |
| Class election with 2 teams | Sports Captain race |
| Yes/No referendum | Multiple individuals running |

Switching mid-setup will offer to reset candidates to the new mode's defaults.

### 4.5 Adding candidates

In the **Candidates / Groups** card:

1. Click **"+ Add Group"** (or "+ Add Candidate" in candidate mode)
2. A new row appears with a default name and symbol
3. Click the name field to edit it (max 40 chars, supports Hindi: `"लोक एकता मंच"`)
4. Click the **symbol button** (large emoji on the right) to open the symbol picker

> 📷 **SCREENSHOT [06-symbol-picker.png]** *Suggested capture: the symbol picker modal*
>
> **What you should see:** A grid of emoji symbols (🍎 🚲 🪁 🦁 🐘 ⏰ 🔦 🔋 🧵 🏏 🎹 📷 🚜 🛳️ 💎 🌻 ⚽ 🪔 🖊️ 📖 🌟 🍋 🚀 ☂️). Already-used symbols are dimmed.

5. Click **✕ delete** to remove a candidate (need minimum 2)
6. **NOTA** is automatically added as the last option — cannot be removed or edited

### 4.6 Adding voters

In the **Voter Roll** card, three ways to add:

#### Option A — Bulk paste
Type or paste names in the box, one per line:
```
Ravi Kumar, 9A
Priya Sharma, 9A
Anil Singh Yadav, 10B
"Sharma, Rajesh", 11C   ← quoted name with comma
Sunita Devi, 12 Sci
```
Click **⊕ Add from Paste**.

#### Option B — CSV upload
Click **📁 Upload CSV** → select a `.csv` file. Format:
```csv
Name,Class
Ravi Kumar,9A
Priya Sharma,9A
```
First row can be header (auto-detected) or skipped.

#### Option C — Type one at a time
After adding voters, click on any voter's name to edit it inline.

> 📷 **SCREENSHOT [07-voter-roll.png]** *Suggested capture: voter list with class badges*
>
> **What you should see:** Stats bar at top (Total / Voted / Pending / Turnout). Below it the bulk-paste textarea, and a grid of voter cards. Each card shows: serial number, blue class badge (e.g., "9A"), voter name, and ✕ remove button. A class filter dropdown appears at top-right when class data exists.

#### Filtering by class
A **filter dropdown** appears once class data exists. Choose a class to see only those voters. Useful for verifying counts per class.

### 4.7 Booth Identity (multi-booth setups)

If running just **one booth**, leave this as default (`BOOTH-1`, "Main Booth").

If running multiple booths, give each unique IDs:
- Booth #1: BOOTH-1 / "Class 6-8 · Hall A"
- Booth #2: BOOTH-2 / "Class 9-10 · Hall B"
- Booth #3: BOOTH-3 / "Class 11-12 · Library"

Voter IDs will be prefixed automatically: `BOOTH-1-V0001`, `BOOTH-2-V0001`, etc.

### 4.8 Pre-flight check

Below the **Start Election** card, you'll see a **green ready box** if everything is configured:

> 📷 **SCREENSHOT [08-precheck-ready.png]** *Suggested capture: green pre-check banner*
>
> **What you should see:** Green box with checkmark: *"✓ Ready to start. 4 candidates · 612 voters registered."*

If something's missing, you'll see a **yellow warning box** listing issues:
- Need at least 2 candidates
- Need at least 1 voter
- Election title is empty
- Some candidates have empty names

Fix the issues. The Start button still works but voting may fail.

### 4.9 Start the election

Click **🚀 Start Voting Now →**. A confirmation modal appears:

> 📷 **SCREENSHOT [09-start-confirm.png]** *Suggested capture: start election confirmation*
>
> **What you should see:** Modal asking *"Start Election?"* with election summary and warnings:
> - Once started: Candidate list will be locked
> - Voters cannot be removed
> - Voting begins immediately

Click **🗳️ Yes, Start Voting**. The system switches to the **Voting tab** and the election goes live.

⚠️ **After this point:** the Setup tab is locked. You cannot add/remove candidates or voters until you end voting.

---

## 5. Running the Election Day

### 5.1 The Voting screen

> 📷 **SCREENSHOT [10-voting-screen.png]** *Suggested capture: full voting screen with EVM*
>
> **What you should see (top to bottom):**
> 1. Hero bar with election title, 🔴 LIVE pill, vote count, time
> 2. Red emergency bar (in Institution mode): "🔒 VOTING IN PROGRESS — Setup is locked. To make changes, end the election first."
> 3. Tab navigation (Setup tab is greyed out / disabled)
> 4. Dark navy "voting stage" containing:
>    - Election title + date subtitle
>    - "⏸ Pause" and "🛑 End Voting" buttons (top-right)
>    - **Voter Queue strip** — horizontal cards showing current voter (highlighted orange) + next 7
>    - **Process steps pills**: 1. CALL VOTER → 2. PRESS BALLOT → 3. VOTER VOTES → 4. VVPAT VERIFY → 5. NEXT VOTER (current step glows gold)
>    - **3-column EVM grid:**
>      - LEFT: **Control Unit (CU)** — green display reading "READY", power/busy lights, big BALLOT button, Result Section with 4 buttons (Total / Close / Result / Clear)
>      - CENTER: **Ballot Unit (BU)** — list of candidates with names, symbols, blue vote buttons, red LEDs
>      - RIGHT: **VVPAT Printer** — black window for slip drop, timer bar, scrolling status log

### 5.2 The voting process (per voter)

This is the **standard 6-step ECI procedure**. Teachers/officers should follow this:

#### Step 1: Voter approaches the booth
Polling Officer 1 (PO1) checks voter ID and finds their name in the **Voter Queue strip**. The current voter is highlighted in **orange** at the front of the queue.

#### Step 2: Apply indelible ink
Polling Officer 2 (PO2) marks voter's left index finger with marker (real or symbolic).

#### Step 3: Press BALLOT
Polling Officer 3 (PO3) presses the big orange **BALLOT** button on the Control Unit.
- CU display changes from "READY" to "READY" (green)
- BU's "READY" lamp glows green (top-right of BU)
- A subtle beep plays

> ✅ **What this signals:** The Ballot Unit is now active for ONE vote.

#### Step 4: Voter casts vote
Voter goes behind the curtain (privacy) and presses ONE blue vote button next to their preferred candidate.
- Red LED next to candidate lights up
- A "vote registered" sound plays

#### Step 5: VVPAT verification
A paper slip drops in the VVPAT window for **3 seconds** (or 7 seconds in India mode). The slip shows:
- Serial number
- Candidate symbol
- Candidate name

> 📷 **SCREENSHOT [11-vvpat-slip.png]** *Suggested capture: VVPAT showing dropped slip*
>
> **What you should see:** White paper slip in the black VVPAT window with header "SUNRISE EA · 2026", a candidate's symbol (large), and their name in caps. Timer bar at bottom fills green over 3 seconds.

After the timer ends, the slip slides down (animated) and disappears (simulating the slip dropping into a sealed box).

#### Step 6: Next voter
- A green popup appears: **"☝️ Vote Recorded · [Voter Name] · मतदान सम्पन्न"** (1.8 sec)
- Voter Queue advances — current voter marked ✓ done, next voter highlighted orange
- CU display returns to "READY"
- Process pills reset to step 1

**Repeat for next voter.**

### 5.3 Live progress

Throughout voting, watch the top hero bar:

> 📷 **SCREENSHOT [12-live-progress.png]** *Suggested capture: hero bar with LIVE pill and counts*
>
> **What you should see:** Pills showing:
> - 🔴 LIVE (red, pulsing dot)
> - 👥 152 / 600 voted
> - 🕐 11:47

### 5.4 Pausing voting (lunch break, etc.)

Click **⏸ Pause** button (top-right of voting stage). Enter admin password. Voting is paused. Click again to resume.

While paused, the BALLOT button still works (votes can be cast) but the status pill shows ⏸ Paused.

### 5.5 Auto-backup

Every **10 votes** (or whatever interval you set in Setup), a JSON file is auto-downloaded to your Downloads folder named like:
```
autobackup-Sunrise_School_Election_2026_27-150votes.json
```
**You don't need to do anything** — these are insurance against accidental data loss. You can keep them or delete them after the election ends successfully.

### 5.6 What if a voter is missing from the roll?

You **cannot** add voters once voting has started. Options:
1. End voting (admin password) → switch to Setup → add the voter → restart voting (BUT this resets all votes — bad!)
2. Better: maintain a **paper backup voter roll** (printed via Print Kit). If someone is missing, note them on paper and resolve after the election.

---

## 6. End of Day — Closing & Results

### 6.1 The CRC Sequence (mock poll demo)

The Control Unit has 4 buttons that follow real EVM protocol:

| Button | Purpose | When to use |
|---|---|---|
| **Total** | Display current vote count | Mid-poll, just to verify |
| **Close** | Lock the EVM, no more votes | End of voting day |
| **Result** | Cycle through each candidate's count | After Close |
| **Clear** | Reset all data, fresh poll | After Result (for mock polls only) |

> 📷 **SCREENSHOT [13-cu-buttons.png]** *Suggested capture: CU result section with 4 buttons*

### 6.2 Officially ending the election

When voting is complete (all voters done, or end of allotted time):

#### Path A — Quick End (recommended for real elections)
Click the big **🛑 End Voting** button at the top-right of the voting stage.
- Confirmation modal: *"End Voting? This will close the election and reveal results. Cast: 487 · Remaining voters: 113"*
- Click **🛑 Yes, End Voting**
- System auto-saves a final JSON backup
- Switches to **Results tab** automatically

#### Path B — CRC Demo (educational)
1. Press **Close** on CU → display shows "CLOSED" → no screen change
2. Press **Result** on CU → counts cycle on display (C1:42, C2:31, C3:8, ...) → ends with "WIN: 🖊️"
3. Modal asks: *"Show full results screen with charts and downloads?"* → click Yes

### 6.3 The Results screen

> 📷 **SCREENSHOT [14-results-screen.png]** *Suggested capture: full results screen*
>
> **What you should see:**
> - Top: **Winner Banner** (gold gradient) — "🏆 WINNER · School Captain", giant symbol, winner's name, vote count + percentage
> - Stats row: Total Voters · Votes Cast · Turnout · Winning Margin
> - **Vote Tally** with horizontal bars showing each candidate's votes/percentage
> - **Action buttons:** ⬇ CSV · ⬇ JSON · 🏆 Winner Certificate · 🖨 Print
> - **Archive & New Election** card at bottom (red border)
> - **Past Elections (History)** card

### 6.4 Generating the winner certificate

Click **🏆 Winner Certificate** button.

> 📷 **SCREENSHOT [15-certificate.png]** *Suggested capture: full winner certificate*
>
> **What you should see:** A printable A4-style certificate with:
> - Triple gold/navy borders + ornamental corner flourishes
> - "SUNRISE EDUCATION ACADEMY" gold ribbon banner at top
> - Sunrise SEA logo medallion
> - Title: "Certificate of Election" (italic gold position label)
> - Winner's name in large Playfair Display serif with gold gradient underline
> - Symbol in golden medallion
> - Stats panel: Votes Received · Vote Share · Turnout
> - Date (left) · Wax seal (center) · Signature (right)
> - Footer: "Generated digitally by Sunrise Voting Station"

Click **⬇ Download PNG** to save the certificate. You can then print it on photo paper or A4.

### 6.5 Downloading data

| Button | What you get |
|---|---|
| **⬇ CSV** | Spreadsheet of all candidates, votes, percentages, voter roll |
| **⬇ JSON** | Full election data (use for merging if multi-booth) |
| **🏆 Winner Certificate** | PNG image of cert |
| **🖨 Print** | Browser print dialog (saves to PDF too) |

### 6.6 Archiving (preserve forever)

After election is officially closed:
1. Click **📦 Archive & Start New Election** (red button at bottom)
2. Enter admin password
3. Confirm: *"This will move the current election to permanent history and reset the system for a new election."*
4. Click **Archive & Reset**

The election is now in the **History** card permanently — visible forever, including winner. The system is now ready for a new election.

> ⚠️ **Once archived, you cannot vote in or modify that election again.** History entries are read-only.

---

## 7. Multi-Booth Election

> ⚡ **NEW: Multi-booth setup is now ONE-CLICK!** Read 7.3 below first — it replaces the manual setup steps.

### 7.1 When to use multiple booths

For 200+ voters, a single booth becomes a bottleneck. Math:
- Single booth at 30 sec/voter × 600 voters = 5+ hours straight
- 4 booths at 30 sec/voter × 150 voters each = ~75 minutes (parallel)

### 7.2 Recommended split for 650+ voters

| Booth | Classes | Approx voters |
|---|---|---|
| BOOTH-1 | Class 6-7 | ~165 |
| BOOTH-2 | Class 8-9 | ~165 |
| BOOTH-3 | Class 10-11 | ~165 |
| BOOTH-4 | Class 12 + Repeats | ~155 |

**Critical rule:** Each student appears in **exactly ONE booth's voter roll**. This physically prevents double-voting.

### 7.3 ⚡ ONE-CLICK Booth Setup (recommended — kills 90% of multi-booth pain)

**Problem this solves:** Before, each booth had to be manually configured with the same candidate names, symbols, election title, and Firebase config. Easy to make typos. Frustrating for non-tech staff.

**New solution:** Master booth generates a **QR code / share link**. Other booths just scan it (or open the URL) and they auto-configure.

#### Steps:

1. **Set up the FIRST booth completely** — pick a template, edit candidates, configure Firebase if using cloud sync. **Don't import voters yet.**
2. In Setup → **Booth Identity** card → click **🔗 Share with Other Booths**
3. A modal opens with:
   - A big **QR code** (300×300 PNG)
   - A **Share Link** with the entire config encoded
   - A "Copy Link" button
4. **On every other booth device:**
   - Either **scan the QR code** with the phone/tablet camera (opens the URL automatically), OR
   - **Open the Share Link** in their browser
5. The booth detects the join URL → asks for admin password → shows a confirmation modal:
   > "Another booth has shared this election setup with you: [Election Title], [Position]. CANDIDATES: [list]. Click Yes, Join to load these settings."
6. Click **✓ Yes, Join** → booth auto-imports:
   - Election title, position, date, type
   - Full candidate list (names + symbols, exact match)
   - Firebase RTDB URL + Election Key (if cloud sync was enabled on master)
   - Auto-assigned Booth ID (BOOTH-2, BOOTH-3, etc. — random unique number)
7. Now each booth just imports **its own assigned voters** and starts.

> ✅ **No manual entry of candidate names. No copy-pasting Firebase URLs. No risk of typos breaking the merge.**

The share link is fully self-contained — works even without internet (just open the link locally).

### 7.4 Setup steps (manual / fallback)

#### Per booth (do on each device):
1. Copy the entire `voting-station/` folder to that device
2. Open `index.html` → Institution Mode (use same admin password on all booths)
3. Set the **same**:
   - Election Title
   - Position
   - Election Date
   - Candidates (names AND symbols must match exactly)
4. Set **unique** Booth ID (BOOTH-1, BOOTH-2, etc.) and Label (e.g., "Class 6-7 · Hall A")
5. Import **only that booth's** voters (filter by class in your master CSV first)
6. Start Election

#### How candidate names must match
For the merge tool to combine results correctly, all booths must use the **exact same** candidate names. Even small differences break the merge:
- ❌ "Group A — Pen" on Booth-1 vs "Group A - Pen" on Booth-2 (different dash) → treated as different candidates
- ✅ Copy-paste candidate names from one booth to others

### 7.4 During the day

Each booth runs **independently**. Officers at each booth follow the standard process. No cross-booth coordination needed during voting.

### 7.5 End of day — combining results

#### Option A — Manual JSON merge (works offline)
1. End voting on each booth → click ⬇ JSON → save the file
2. Collect all JSON files on one master device (USB / WhatsApp / email)
3. Open `voting-station/merge.html` on the master device

> 📷 **SCREENSHOT [16-merge-tool.png]** *Suggested capture: merge.html drop zone*
>
> **What you should see:** A dashed-border "drop zone" with an upload icon, instructions to drag-drop JSONs, and a "Browse Files" button.

4. Drag-drop all booth JSONs into the drop zone
5. Each file appears as a row with booth ID, vote count, validation status
6. Click **🔗 Merge & Show Combined Results →**

> 📷 **SCREENSHOT [17-merge-results.png]** *Suggested capture: merge.html showing combined results*
>
> **What you should see:** Combined winner banner, aggregate stats, candidate tally with **booth-wise breakdown** below each (e.g., "BOOTH-1: 42 · BOOTH-2: 38 · BOOTH-3: 45"). Warnings shown if any inconsistencies found (duplicate voter IDs across booths, etc.).

7. Download:
   - **⬇ CSV** — combined spreadsheet
   - **⬇ JSON** — combined raw data
   - **🏆 Winner Certificate** — PNG with "Combined N booths" subtitle

#### Option B — Auto-merge from Firebase (if cloud sync was on)
1. Open `merge.html`
2. Enter the same Firebase RTDB URL + Election Key (auto-prefilled if same browser)
3. Click **⚡ Auto-Merge Now**
4. Combined results appear instantly — no JSON collection needed

✅ Tick **"Auto-refresh every 30s"** to watch combined results update live during voting.

---

## 8. Cloud Sync & Live Dashboard (Optional)

> ⚠️ This is **optional**. Everything works without it. Cloud sync only adds **live combined dashboard** — useful if the principal wants to watch progress in real-time.

### 8.1 Setting up Firebase (one time, ~5 minutes)

Follow the dedicated guide: **[FIREBASE-SETUP.md](FIREBASE-SETUP.md)**

Quick summary:
1. Go to **https://console.firebase.google.com/** → sign in with Google
2. Create project → name it `sunrise-voting-2026` (or similar)
3. Enable **Realtime Database** → Singapore region → Test mode
4. Copy the database URL (looks like: `https://sunrise-voting-2026-default-rtdb.asia-southeast1.firebasedatabase.app`)

### 8.2 Enabling on each booth

In Setup → **Cloud Sync · Live Dashboard** card:
1. Paste the RTDB URL
2. Type a shared Election Key (e.g., `sunrise-2026-captain`) — must be **same on all booths**
3. Click **🔌 Test Connection** → expect green ✓ "Connection OK · read + write working"
4. Click **✓ Enable Cloud Sync**

> 📷 **SCREENSHOT [18-cloud-sync-active.png]** *Suggested capture: Cloud Sync card showing "✓ Cloud Active"*

### 8.3 Live Dashboard (principal's view)

On the principal's laptop, open `voting-station/live-dashboard.html`:

> 📷 **SCREENSHOT [19-live-dashboard.png]** *Suggested capture: live dashboard in big-screen mode*
>
> **What you should see (dark navy background):**
> - Top bar: "📺 Live Election Dashboard" + 🔴 LIVE pill + last-update time
> - **Lead Card** (gold) — "🏆 LEADING PARTY · Position", giant symbol, name, vote count + lead margin
> - **Stats row** — Total Votes / Voter Roll / Turnout / Booths Active / Lead Margin
> - **Combined Tally** — horizontal bars across all booths
> - **Booth Status Grid** — one tile per booth showing votes/total, status (LIVE/Closed)
> - Bottom action: Big Screen Mode · Refresh · Disconnect

Connect with the same Firebase URL + Election Key, click 📡 Connect. Click **📺 Big Screen Mode** for projector display.

---

## 9. Print Kit — Paper Materials

The print kit generates **all paper documents** needed for offline/backup paper voting.

Open `voting-station/print-kit.html` (also linked from Setup screen).

> 📷 **SCREENSHOT [20-print-kit.png]** *Suggested capture: print-kit.html showing sidebar + preview*
>
> **What you should see:**
> - LEFT sidebar: list of 7 documents (Ballot Paper, Voter Roll, Voter ID Slips, Candidate Poster, Tally Sheet, Result Declaration, Booth Sign)
> - Each item highlights when active
> - At bottom: status info showing election title, position, booth, candidate count, voter count
> - RIGHT main area: A4-sized preview of the selected document

### 9.1 Available documents

| Document | What it does |
|---|---|
| **📜 Ballot Paper** | Printable ballot for paper voting (4 per A4 with cut lines) |
| **📋 Voter Roll** | Class-wise sorted list with sign-off column for officers |
| **🎫 Voter ID Slips** | Token slips (8 per A4) — give to each voter at booth entry |
| **🪧 Candidate Poster** | Large display poster for booth entrance |
| **📊 Tally Sheet** | Vote counting grid (60 cells per candidate) with totals + signatures |
| **🏆 Result Declaration** | Official letterhead form for principal to fill + sign |
| **🏛️ Booth Sign** | Booth number signage for entrance (huge fonts) |

### 9.2 Printing

1. Select document from sidebar
2. Adjust options if shown (e.g., "Ballots per A4: 2 or 4")
3. Click **🖨 Print This Document** (top-right) → browser print dialog
4. Choose printer OR **Save as PDF** to save digitally
5. Print on plain A4 paper

### 9.3 When to use Print Kit

- **Always print Voter Roll** — keep at booth as backup officer reference (in case digital fails)
- **Print Booth Sign** — A4 colorful sign for booth entrance, looks official
- **Optional**: Voter ID Slips if you want a formal token system
- **In emergencies**: Ballot Paper + Tally Sheet for full paper election fallback

---

## 10. Guest Mode for Students

Use Guest Mode for educational purposes — let students explore how Indian elections work.

> 📷 **SCREENSHOT [21-guest-scenario-picker.png]** *Suggested capture: guest scenario picker*
>
> **What you should see:**
> - Header: "🎓 Guest Mode · Choose a Scenario" on navy background
> - Two tab pills: "🇮🇳 Real India Elections" (active by default) and "🎉 Fun Classroom"
> - Grid of scenario cards (3 per category)
> - Footer: "← Back to Mode Selection" + privacy note

### 10.1 Real India Election scenarios

| Scenario | Position | Candidates | Voters |
|---|---|---|---|
| 🏛 **Lok Sabha Mock Election** | Member of Parliament (सांसद) | 7 fictional national parties + Independent + NOTA | 10 |
| 🏯 **Vidhan Sabha Mock Election** | MLA (विधायक) | 5 fictional state parties + NOTA | 8 |
| 🏘 **Panchayat Mock Election** | Sarpanch (सरपंच) | 4 individual candidates + NOTA | 6 |

### 10.2 Fun Classroom scenarios

| Scenario | Position | Candidates | Voters |
|---|---|---|---|
| 🐾 **Best Pet 2026** | Cutest Pet | Dog, Cat, Parrot, Rabbit + NOTA | 6 |
| 📚 **Favorite Subject** | Most Loved Subject | Math, Science, History, Art + NOTA | 7 |
| 🪔 **Best Festival** | Most Loved Festival | Diwali, Holi, Eid, Christmas + NOTA | 6 |

### 10.3 What students experience

- **Demo Mode green ribbon** at top — clear that this isn't a real election
- **7-second VVPAT** for India scenarios (real ECI standard)
- **3-second VVPAT** for Fun scenarios
- **Educational facts** rotate during India scenarios:
  - "EVMs were first used in India in 1982, in the Paravur constituency of Kerala."
  - "VVPAT was introduced in 2013 in Nagaland."
  - "The NOTA option was added in 2013 by the Supreme Court."
- **Hindi labels** on India scenarios for authentic experience

### 10.4 Try Different Scenario

In the green ribbon at top, click **🔄 Try Different Scenario** to go back to the picker without exiting.

### 10.5 Exit to Home

Click **⊗ Exit to Home** to return to the landing screen. All Guest data is wiped.

---

## 11. AI Features (Gemini)

The voting station includes optional **Google Gemini AI** integration for tasks that need intelligent text understanding. **Free tier** is available — no credit card needed.

### 11.1 What AI helps with

| Where | What it does |
|---|---|
| **Voter Roll** → "✨ Smart Parse with AI" | Cleans up messy paste — handles PDF dumps, Word lists, numbered formats, class headers, footers, etc. |
| **Print Kit** → Result Declaration → "✨ AI: Draft Declaration" | Auto-writes a formal declaration paragraph based on election data |

### 11.2 One-time setup — get a free Gemini API key (~1 min)

1. Open https://aistudio.google.com/apikey in a new tab
2. Sign in with your Google account (school's Gmail or personal)
3. Click **"+ Create API Key"** (top of the page)
4. Choose "Create API key in new project" → wait ~5 seconds
5. Copy the key (looks like `AIzaSy...` — about 40 characters)

**Free tier limits:**
- 15 requests per minute
- 1500 requests per day
- 1 million tokens per minute

(For a school: parsing 10 class lists + drafting 5 declarations = well within free tier.)

### 11.3 Adding the key to the voting station

1. Open `voting-station/index.html` → Institution Mode
2. Scroll to **Voter Roll** card
3. Click **🔑 AI Settings** button (top-right of voter section)
4. Paste the key into the input field
5. Click **"Save & Continue"**
6. Done — same key works across all AI features in the system

> 🔒 The key is stored only in your browser's localStorage. It's never sent anywhere except Google's servers when you actually use an AI feature.

### 11.4 Smart Parse for messy student lists

**Use case:** Teacher copies the class list from a Word document where it looks like:

```
Class 9A Students - Session 2026-27
S.No  Student Name              Father's Name      Roll
1.    Ravi Kumar Sharma         Suresh Sharma      24
2.    Priya Devi                Mahesh Choudhary   25
3.    Anil Singh Yadav          Mohan Singh        26
                  Page 1 of 3
4.    Sunita Bishnoi            Khinya Ram         27
...
```

The standard "Add from Paste" can't parse this. **Smart Parse with AI** can:

1. Paste the messy text into the textarea
2. Click **✨ Smart Parse with AI**
3. AI extracts just the names + auto-detects "Class 9A" header → applies to all students
4. Returns clean list, ready to vote

> 📷 **SCREENSHOT [22-smart-parse.png]** *Suggested capture: Voter Roll card with Smart Parse button*
>
> **What you should see:** Two parse buttons side-by-side: blue "⊕ Add from Paste" (offline parser) and green "✨ Smart Parse with AI" (Gemini AI). Plus a 🔑 AI Settings button on the right.

### 11.5 AI for Result Declaration

When you generate a **Result Declaration** form (Print Kit → 🏆 Result Declaration), there's a green button **✨ AI: Draft Declaration**:

1. Click it
2. AI generates a formal 3-4 sentence paragraph like:
   > "I hereby declare that [Winner Name] has been duly elected to the position of [Position] in the [Election Title] held on [Date], having received [N] votes out of [Total] cast (turnout: X%). The election was conducted in accordance with school regulations..."
3. The text appears above the form
4. When you print, only the declaration text is included (the AI button itself is hidden in print)

### 11.6 What if I don't want to use AI?

**Everything works without AI.** AI features are purely optional upgrades:
- **Add from Paste** (the original parser) handles standard `Name, Class` format
- The improved heuristic parser also handles numbered lists (1. 2. 3.), pipe separators, "Class 9A:" headers, and tab-separated columns
- Result Declaration form has fillable blanks for principal to write by hand

If you skip AI setup, the system still works 100% — you just lose the smart features.

### 11.7 Privacy

- ✅ Your Gemini key is stored only in this browser
- ✅ Voter names sent to Gemini for parsing are NOT stored by Google after the request (per Google's free-tier policy)
- ⚠️ Treat the API key like a password — don't share it publicly
- ⚠️ If the school uses a personal Gmail account, that account's quota is consumed (still free)

### 11.8 Troubleshooting AI features

| Issue | Fix |
|---|---|
| "No Gemini API key set" | Click 🔑 AI Settings → paste key → Save |
| "Invalid API key" / HTTP 401 | Key was wrong or revoked — generate a new one at aistudio.google.com/apikey |
| "Quota exceeded" / HTTP 429 | Wait 1 minute, retry. Free tier: 15 req/min, 1500/day |
| AI extracts wrong names | Edit the text to add clearer headings, then retry. Or use manual "Add from Paste" |
| Smart Parse button does nothing | Open browser console (F12) → check for network errors → may be no internet connection |

---

## 12. Troubleshooting

### 11.1 "I forgot the admin password"
There's no password recovery. To reset:
1. Open the voting station in browser
2. Press **F12** to open Developer Console
3. Go to **Console** tab
4. Type: `localStorage.clear()` and press Enter
5. Refresh the page → password is now back to default `sunrise2026`

⚠️ **This wipes ALL data** including elections in progress and history. Use only as last resort.

### 11.2 "The page won't open"
- Check you're using Chrome / Edge / Firefox (NOT Internet Explorer)
- Right-click `index.html` → Open With → Chrome
- If browser warns about "scripts blocked", click "Allow"

### 11.3 "I clicked something and got a password prompt I didn't expect"
In **Institution mode**, the following actions require password:
- End Voting / Close
- View Total
- Pause / Resume
- Archive & Reset
- Change Password
- Show Result

In **Guest mode**, NONE require password — they all proceed immediately.

### 11.4 "The Voting tab is greyed out"
This means setup isn't complete. Either:
- Election hasn't been started yet (click 🚀 Start Voting Now)
- Election was already closed (look at status pill — should say "Closed")
- No voters registered

### 11.5 "Setup tab is locked"
This is intentional. Once voting is live, setup is locked. To unlock:
1. Click 🛑 End Voting (admin password) → switches to Results tab
2. Click 📦 Archive & Start New Election
3. Setup tab is now accessible

⚠️ This permanently archives the current election — you cannot resume.

### 11.6 "Auto-backup isn't downloading"
Browser may have blocked the first download. Check:
- Browser address bar for a "blocked" icon
- Click it and choose "Always allow"
- The next vote will trigger another auto-backup

### 11.7 "Cloud Sync says ⚠ HTTP 401/403"
Firebase rules aren't open. Go to Firebase Console → Realtime Database → Rules. Set:
```json
{
  "rules": {
    ".read": true,
    ".write": true
  }
}
```
Click Publish.

### 11.8 "Live Dashboard shows nothing"
- Check both URL and Election Key match exactly what's set on the booth(s)
- Click 🔄 Refresh Now
- Check status pill — if it says ⚠ HTTP error, your Firebase rules are blocking
- Check at least ONE booth has Cloud Sync enabled and has cast votes

### 11.9 "Merge tool shows wrong totals"
- Check all booth JSONs have the same candidate names (exact match)
- Look at Warnings panel above results
- Common issue: trailing space differences ("Group A " vs "Group A")

### 11.10 "Power cut during voting"
- Browser tab closed → reopen → election state is restored from localStorage
- Computer rebooted → reopen → election state is restored
- All votes up to last save are preserved
- The auto-backup JSON files in your Downloads folder are extra insurance

### 11.11 "Internet went down during voting"
- Voting **continues** offline (this is the design)
- Cloud Sync queues votes locally — toast shows "⚠ Cloud sync failed"
- When internet returns, future votes sync; old queued votes WON'T retry (limitation)
- **End-of-day truth is from local JSON downloads** — not Firebase. Firebase is just a live mirror.

---

## 13. Roles & Responsibilities

A school election typically has these roles:

### Presiding Officer (PrO) — usually a Senior Teacher or Principal
- Sets up the election in **Institution Mode**
- Configures candidates, voters
- Has the **admin password**
- Closes the election at end of day
- Generates results, certificate, declaration form
- Archives the election

### Polling Officer 1 (PO1) — at booth entrance
- Checks each voter's ID (Voter ID slip from Print Kit, or class roll)
- Verifies they're on the voter list (in voter queue)
- Allows them to enter

### Polling Officer 2 (PO2) — between PO1 and PO3
- Marks voter's left index finger with indelible ink (real or marker)

### Polling Officer 3 (PO3) — at the EVM
- Sits with the laptop / tablet
- Presses the **BALLOT** button to release vote
- Watches the voter cast their vote
- Confirms VVPAT slip dropped correctly
- Calls next voter

### Counting Officer — at end of day
- Witnesses CRC sequence (Close → Result → Clear/Archive)
- Signs the Result Declaration form
- Helps merge results from multiple booths

### Polling Agent (optional) — student/staff representative per candidate
- Watches the process for fairness
- Witnesses sealing/closing
- Signs the result declaration

---

## 14. Glossary

| Term | Meaning |
|---|---|
| **EVM** | Electronic Voting Machine (the digital ballot box) |
| **CU** | Control Unit — the master device with display + buttons |
| **BU** | Ballot Unit — where the candidate buttons are |
| **VVPAT** | Voter Verifiable Paper Audit Trail — the slip that briefly shows your vote |
| **NOTA** | None Of The Above — a valid choice meaning "I don't approve any candidate" |
| **CRC** | Close → Result → Clear (the standard ECI mock-poll demo sequence) |
| **PrO** | Presiding Officer (the person in charge of the booth) |
| **PO1, PO2, PO3** | Polling Officers (three roles at each booth) |
| **MLA** | Member of Legislative Assembly (विधायक) — state-level legislator |
| **MP** | Member of Parliament (सांसद) — national-level legislator |
| **Sarpanch** | Village panchayat head (सरपंच) — local-level elected leader |
| **Tendered Vote** | A backup paper ballot when someone has already voted in your name |
| **Indelible Ink** | The blue ink mark on left index finger lasting ~15 days |
| **RTDB** | Realtime Database (Firebase product used for cloud sync) |
| **Election Key** | A unique identifier shared across booths for cloud sync |

---

## 📎 Quick Links

- **[QUICK-REFERENCE-CARD.md](QUICK-REFERENCE-CARD.md)** — 1-page cheat sheet for booth officers
- **[FIREBASE-SETUP.md](FIREBASE-SETUP.md)** — Firebase setup in 5 minutes
- **[CONNECTING-BOOTHS.md](CONNECTING-BOOTHS.md)** — Multi-booth deployment options

---

**For technical issues during the election day, refer to [Section 11: Troubleshooting](#11-troubleshooting) first. Keep this guide accessible on the principal's device.**

🏫 **Sunrise Education Academy · Samdari · 2026-27**
*Built for Electoral Literacy Club (ELC)*