An adaptive AI tutor & assistant that helps users understand their country's election process — personalized to their knowledge level, translated into their language, and spoken aloud in their voice.
Most civic education tools treat every user the same. BallotIQ doesn't.
When you open BallotIQ, you choose how you want to learn:
- Guided Path — A 3-question diagnostic figures out what you already know, then Gemini builds a personalized learning path just for you. Micro-quizzes after each step check your understanding. Get two wrong in a row and the app automatically switches to simpler explanations. Finish with a certification quiz personalized to what you actually studied.
- Open Chat — Skip the structure and just talk to the AI assistant directly. Ask whatever you want about your country's election process.
The entire platform — every label, button, content block, and AI response — translates in real time into 8 languages. Google Cloud TTS then reads everything aloud in your selected language, so a Tamil-speaking first-time voter gets both the text and the audio in Tamil.
| Service | What it does in BallotIQ |
|---|---|
| Gemini 2.5 and 3.1 Flash &/ Flash Lite Models | Assessment analysis, personalized guide generation, micro-quizzes, re-explanations, final quiz, conversational assistant, performance insights |
| Firebase Firestore | Session persistence, 24h guide caching, rate limit tracking, chat history |
| Firebase Auth | Anonymous sessions — required for all Firestore operations |
| Firebase Analytics | 7 custom learning events tracking the full user journey |
| Google Cloud Translation | Real-time full-UI translation into 8 languages |
| Google Cloud TTS | Reads all content aloud in the user's selected language |
| Google Maps Places API | Country selector autocomplete + polling station finder |
Removing any one of these breaks the app. Each is load-bearing.
git clone https://github.com/yourusername/ballotiq
cd ballotiq
npm installCreate .env.local:
NEXT_PUBLIC_GEMINI_API_KEY=
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
NEXT_PUBLIC_TRANSLATE_API_KEY=
NEXT_PUBLIC_TTS_API_KEY=
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=npm run dev # development
npm run build # static export to /out
npm test # 50+ test casesDeployed on Google Cloud Run.
A lightweight liveness health check is available at /api/health which returns 200 OK as long as the server is running (with zero I/O or database queries to minimize latency and cold start times).
Configure the liveness probe on Google Cloud Run with:
livenessProbe:
httpGet:
path: /api/health
port: 8080
initialDelaySeconds: 10
periodSeconds: 30
timeoutSeconds: 5
failureThreshold: 3
Non-partisan • Educational only Built with ❤️ — Empowering voters through intelligence.