My Reps is a learning-friendly civic representative lookup for CLI, API, and Cloudflare Pages demos.
It returns a stable JSON envelope for a U.S. address lookup, with a deterministic mock mode for demos and an optional live mode backed by Census Geocoder plus OpenStates/Plural Open.
The product goal is to help curious residents understand who represents them and what those offices do, even if their last civics class was a long time ago.
This project is a public-demo prototype, not an authoritative civic data service.
- Mock mode uses fully synthetic representative records for the public Honolulu Hale fixture address.
- Live mode currently covers state legislators through OpenStates/Plural Open and reports partial coverage.
- The app does not store exact addresses or exact coordinates.
Install dependencies:
npm installRun tests:
npm test
npm run buildRun a local web preview:
npm run pages:previewRun the CLI:
npm run georep -- lookup --address "530 S King St, Honolulu, HI 96813" --mock
npm run georep -- source-status
npm run georep -- schemaStart with CONTRIBUTING.md for local setup and contribution workflow.
The key design idea is that the CLI, API, and web UI are adapters over a shared TypeScript core. See docs/architecture.md for the dependency direction and request flow.
Tests are organized around the project seams: core, API, CLI, web UI, smoke, and browser e2e. See docs/testing.md for the map.
Future product direction is tracked in docs/roadmap.md.
Live mode requires a server-side OpenStates key:
OPENSTATES_API_KEY=... GEOREP_MODE=live npm run georep -- lookup --address "530 S King St, Honolulu, HI 96813"Cloudflare Pages deployment notes are in docs/cloudflare-pages.md.
Mock data is synthetic and intentionally fake.
Live mode can use the Census Bureau Data API and OpenStates/Plural Open. This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau. OpenStates data is provided by Plural Open; attribution is appreciated by the upstream project.