# Firebase Setup — 5-Minute Guide

This is **optional**. The voting station works perfectly offline without Firebase. Cloud Sync only adds the **live combined dashboard** that shows real-time tally across all booths.

## What you get with Cloud Sync

- 📺 **Live Dashboard** — principal/admin can watch combined results update in real-time across all booths
- 🔄 Each vote is automatically pushed to Firebase (fire-and-forget, won't slow voting)
- ✅ If internet drops, voting continues offline — votes resync when connection returns
- 🛡️ End-of-day results are still computed from local JSON files (cloud is for **live view only**, not source of truth)

## What you DON'T need it for

- Recording votes (always saved locally)
- Generating results (uses local JSON)
- Combining final results (use `merge.html` instead)

---

## Step 1 — Create Firebase project (2 min)

1. Go to **https://console.firebase.google.com/**
2. Sign in with any Google account
3. Click **"Add Project"** (or "Create a Project")
4. Name it something like `sunrise-voting-2026`
5. Skip Google Analytics (toggle off) → **Continue**
6. Wait for project creation (~30 seconds)

## Step 2 — Add Realtime Database (2 min)

1. In the left sidebar, click **"Build" → "Realtime Database"**
2. Click **"Create Database"**
3. Choose any location (closest is fine — e.g., `Singapore`)
4. **IMPORTANT:** Select **"Start in test mode"** (allows public read/write for 30 days)
5. Click **"Enable"**
6. Once created, copy the URL at the top — looks like:
   ```
   https://sunrise-voting-2026-default-rtdb.firebaseio.com/
   ```
   Save this URL — you'll paste it into the voting station.

## Step 3 — Configure Voting Station (1 min)

1. Open the voting station on any booth device
2. Scroll to the **"☁️ Cloud Sync · Live Dashboard"** card in Setup
3. Paste the RTDB URL into **"Firebase RTDB URL"**
4. Choose any **Election Key** (e.g., `sunrise-2026-captain`) — must be the **same on all booths**
5. Click **"🔌 Test Connection"** — should show ✓ green success
6. Click **"✓ Enable Cloud Sync"**

Repeat on every booth device. **Use the same RTDB URL and Election Key on all booths.**

## Step 4 — Open Live Dashboard

On the principal's laptop (or any device with a screen for the audience):

1. Open `voting-station/live-dashboard.html`
2. Paste the same RTDB URL and Election Key
3. Click **"📡 Connect"**
4. Tap **"📺 Big Screen Mode"** for projector display

The dashboard polls every 3 seconds and shows:
- 🏆 Current leading candidate/party (combined across all booths)
- 📊 Live tally bars
- 🏛️ Per-booth status and vote counts
- ⏱ Turnout %, lead margin, total votes

---

## After the election — secure your data

By default, "test mode" rules expire in 30 days and allow public access. After elections:

1. Go to Firebase Console → Realtime Database → **Rules**
2. Replace with locked-down rules:
   ```json
   {
     "rules": {
       ".read": false,
       ".write": false
     }
   }
   ```
3. Click **"Publish"**

Your data is preserved in the database but no one can read or write without explicit permissions.

To delete the data entirely: Realtime Database → click the root (`...`) → delete.

---

## Troubleshooting

| Problem | Fix |
|---|---|
| "Test Connection" fails with HTTP 401/403 | Database is not in test mode. Go to Rules tab, set `".read": true, ".write": true` temporarily. |
| Dashboard shows "Connecting..." forever | Check the RTDB URL exactly matches (including `https://`). No trailing slash needed. |
| Votes show on booth but not on dashboard | Confirm same Election Key on all devices (case-sensitive). |
| Booth says "Cloud sync failed" sometimes | Internet hiccup — votes are queued locally. Will auto-retry when connection returns. |
| Free tier limits | Free Spark plan: 100 simultaneous connections, 1 GB storage. A school election uses < 0.01 GB. |

---

## Privacy notes

- Cloud Sync never uploads voter names — only **anonymous serial numbers** (V0001, V0002...) and the candidate they voted for
- Voter rolls and personal info stay on the booth device only
- The cloud database stores only: vote events, candidate metadata, booth status

If you have any concerns, simply **disable Cloud Sync**. Everything else still works.