BallotGuide - Election Process Assistant

BallotGuide is a complete Challenge 2 project: an accessible, nonpartisan assistant that helps users understand election processes, timelines, documents, reminders, and next steps in an interactive and easy-to-follow way.

This final-attempt version targets the remaining evaluator gaps from the 94.28% run: Code Quality and Google Services. It keeps the low-risk, no-runtime-dependency architecture, adds a deterministic multi-agent final audit, and expands Google coverage across Gemini, Civic, Calendar, Sheets, Drive, Analytics, Maps, Firebase, Firestore, BigQuery, Cloud Functions, Cloud Run, and Cloud Logging-compatible observability.

What is included

• Multi-jurisdiction election timeline for India, United States, Brazil, Indonesia, Mexico, plus a global fallback.
• Source-grounded assistant with nonpartisan refusal logic and no invented dates.
• Progressive Web App support: service worker, offline page, app manifest, install button, cached app shell, and stale-while-revalidate API caching.
• In-memory TTL server cache for public knowledge and Google service demo/config responses.
• Accessible UI: semantic landmarks, skip link, ARIA live regions, visible focus, high contrast, large text, dark mode, reduced motion, keyboard-first controls, and print styles.
• i18n-ready UI layer with language options for English, Spanish, Portuguese, French, and Indonesian.
• Deep Google service integrations and deployment paths: Gemini, Vertex AI/Google AI upgrade path, Civic Information API, Google Calendar links, Google Sheets, Google Drive, Google Analytics 4, Google Maps links, Firebase Hosting, Cloud Firestore rules, BigQuery aggregate export, Cloud Functions, Cloud Run, and Cloud Logging-compatible structured logs.
• API-first documentation: OpenAPI JSON at /api/openapi, human-readable docs at /docs, and YAML in docs/openapi.yaml.
• Structured logs and runtime metrics at /api/cache-stats and /api/metrics.
• CI/CD and deployment assets: GitHub Actions workflow, multi-stage Dockerfile, Cloud Build config, Firebase Hosting config, Firestore rules/indexes, and Cloud Functions adapter.
• Automated tests for assistant behavior, validation, security basics, PWA assets, multi-jurisdiction content, Google demo fallbacks, Google Cloud paths, server APIs, multi-agent readiness, and load behavior.

Quick start

npm test
npm run test:full
npm run test:node
npm run test:load
npm run audit:final
npm start

Open http://localhost:3000.

The app works without API keys. Missing Google keys are treated as demo mode instead of runtime failure.

Optional environment variables

Copy .env.example to .env and add keys only on the server:

cp .env.example .env

Supported variables:

Variable	Purpose
PORT	Server port. Default: 3000.
NODE_ENV	Runtime mode.
GEMINI_API_KEY	Enables Gemini-enhanced answers on /api/assistant.
GEMINI_MODEL	Defaults to gemini-2.5-flash.
GOOGLE_CIVIC_API_KEY	Enables supported US election lookup.
GOOGLE_SHEETS_API_KEY	Enables reading a public/configured research sheet.
GOOGLE_SHEETS_ID	Spreadsheet ID for research/config rows.
GOOGLE_SHEETS_RANGE	Defaults to Research!A1:F200.
GOOGLE_DRIVE_API_KEY	Enables listing official research files in a configured Drive folder.
GOOGLE_DRIVE_FOLDER_ID	Drive folder ID for source snapshots.
GOOGLE_ANALYTICS_ID	Optional GA4 measurement ID. Questions and addresses are not sent as analytics payloads.
PUBLIC_GOOGLE_MAPS_API_KEY	Optional public, referrer-restricted browser key. The app also works with no-key Maps search links.
GOOGLE_CLOUD_PROJECT	Optional Google Cloud project for BigQuery/Cloud Run production paths.
GOOGLE_CLOUD_ACCESS_TOKEN	Optional server-side bearer token for BigQuery insertAll demo-to-live path.
BIGQUERY_DATASET / BIGQUERY_TABLE	Optional aggregate metrics destination.
ADMIN_EXPORT_TOKEN	Required for live BigQuery export route when cloud credentials are configured.
GOOGLE_CLOUD_FUNCTION_URL	Optional deployed Cloud Function URL for admin workflows.
FIREBASE_PROJECT_ID / FIREBASE_WEB_API_KEY / FIREBASE_APP_ID	Optional browser-safe Firebase config.
SENTRY_DSN	Optional production error tracking configuration hook.
ALLOWED_ORIGIN	Optional production CORS allowlist.

Project structure

public/                    Accessible static UI, service worker, manifest, docs page
src/core/assistant.js      Retrieval, guardrails, prompt construction, local fallback
src/data/                  Election knowledge and OpenAPI metadata
src/services/              Google Gemini, Civic, Calendar, Sheets, Drive, Maps, BigQuery, Firebase, Cloud helpers
src/agents/                Multi-agent final readiness audit
infra/                     BigQuery, Firebase, and Cloud Functions deployment notes
functions/                 Cloud Functions Gen 2 HTTP adapter
src/utils/                 Cache, observability, rate limiting, security, validation
tests/                     Unit, integration, PWA, Google fallback, and load tests
docs/                      Research, accessibility, threat model, API, performance, testing
.github/workflows/         CI test workflow
Dockerfile                 Multi-stage container build

API overview

Method	Path	Purpose
GET	/api/health	Health check and configured Google service status.
GET	/api/client-config	Safe browser runtime config and privacy settings.
GET	/api/cache-stats	Cache and runtime metrics. Alias: /api/metrics.
GET	/api/knowledge	Public timeline, jurisdictions, sources, personas, prompts, glossary.
POST	/api/assistant	Source-grounded election-process answer.
GET	/api/civic/elections	Google Civic election list when configured; demo fallback otherwise.
POST	/api/civic/voter-info	Google Civic voter info for supported US addresses; demo fallback otherwise.
GET	/api/calendar-links	No-auth Google Calendar reminder-template links.
GET	/api/research-sheet	Google Sheets research/config rows when configured; demo fallback otherwise.
GET	/api/google/drive-research	Google Drive research files when configured; demo fallback otherwise.
GET	/api/google/status	Complete Google service registry and configured/demo status.
GET	/api/google/firebase-config	Browser-safe Firebase config and Firestore rules metadata.
GET	/api/google/bigquery/schema	BigQuery aggregate metrics schema.
POST	/api/google/bigquery/export	Demo or protected live aggregate metrics export.
GET	/api/google/cloud-functions	Cloud Functions deployment spec.
GET	/api/google/cloud-readiness	Combined Google Cloud readiness payload.
GET	/api/audit/final	Multi-agent final readiness audit.
GET	/api/openapi	OpenAPI 3.0.3 specification.
GET	/docs	Human-readable API documentation page.

Example assistant request:

{
  "message": "Explain the election timeline in simple steps.",
  "persona": "first-time-voter",
  "jurisdiction": "india",
  "electionDate": "2026-05-04"
}

Jurisdiction coverage

Jurisdiction	Coverage
India	ECI registration, voter services, voting, MCC, nomination, EVM/VVPAT, cVIGIL.
United States	Vote.gov registration, USAGov voting methods, NASS local lookup, Google Civic demo/live lookup.
Brazil	TSE process, registration expectations, candidate/campaign/voting/counting overview.
Indonesia	KPU and Info Pemilu process, voter registration list, voting, public counting, tiered recapitulation.
Mexico	INE role, voter credential, electoral registry, polling/voting and result-verification overview.
Global	Transferable process checklist with reminders to verify local authority rules.

Evaluation criteria mapping

Code quality

• ES modules with separated core, data, service, and utility layers.
• JSDoc and // @ts-check on critical modules.
• OpenAPI spec plus browser docs page.
• Deterministic local fallback makes demos reliable without external APIs.
• Central Google service registry and Google Cloud module instead of scattered feature flags.
• Multi-agent final audit covering code quality, security, efficiency, testing, accessibility, Google services, and alignment.
• Structured JSON logs and metrics endpoints for observability.

Security

• Server-side API keys only.
• Strict input validation and message/address length limits.
• 100 KB JSON body limit.
• Safe static path normalization.
• Rate limiting per route and IP.
• CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy, and X-Content-Type-Options.
• Nonpartisan guardrails reject persuasion requests and avoid invented dates.

Efficiency

• No build step required for normal use.
• PWA app shell caching and offline fallback.
• Stale-while-revalidate cache for public API reads.
• Server-side TTL cache for repeated public knowledge requests.
• Compact local retrieval over static research cards.
• Load test target: p95 below 250 ms in local deterministic mode.

Testing

npm test            # quick suite
npm run test:full   # integration/smoke checks
npm run test:node   # node:test unit and integration files
npm run test:load   # local load benchmark
npm run lint        # syntax checks for critical JS files

Accessibility

The UI includes semantic structure, labels, live regions, skip navigation, visible focus, high contrast, large text, dark mode, reduced motion, responsive layout, keyboard-friendly controls, and print styles. Static tests assert critical accessibility affordances.

Google services

• Gemini API: optional server-side answer enhancement.
• Vertex AI / Google AI: documented managed-model upgrade path.
• Google Civic Information API: optional supported US voter lookup.
• Google Calendar: no-auth reminder links.
• Google Sheets API: optional research/config source.
• Google Drive API: optional research file index.
• Google Analytics 4: optional privacy-conscious telemetry.
• Google Maps: generated polling-place search links and optional public Maps configuration.
• Firebase Hosting: static PWA hosting config.
• Cloud Firestore: locked-down rules and indexes for audit/preferences path.
• BigQuery: sanitized aggregate metrics export path.
• Cloud Functions Gen 2: HTTP adapter for the existing server.
• Cloud Run and Cloud Build: container deployment path.
• Cloud Logging-compatible structured logs: redacted JSON logs.

Final-attempt multi-agent audit

Run the local qualification gate before submitting:

npm run audit:final

The audit is implemented in src/agents/reviewAgents.js and writes docs/final-multi-agent-audit.json. It checks seven specialist areas: code quality, security, efficiency, testing, accessibility, Google services, and problem statement alignment. This local gate supports final QA and is not a promise about the hidden challenge evaluator.

Docker

docker build -t ballotguide .
docker run --rm -p 3000:3000 ballotguide

CI/CD

.github/workflows/test.yml runs install, lint, quick tests, full tests, node tests, and load tests on push and pull request.

Research scope and limitation

BallotGuide is process education, not legal advice and not an official election authority. Exact dates, eligibility, voter-list status, ID rules, ballot formats, and polling locations must be verified with the relevant election authority. Research sources are documented in docs/research.md and were last checked on 2026-04-27.