Skip to content
CivicDogCivicDog

Engineering Overview

CivicDog is an evolving, production civic-tech product suite: an ETL pipeline that syncs U.S. Congress members, bills, and roll call votes from the official government API, a REST API that serves it — including a semantic search API that answers natural-language questions about legislation — an app backend and React web app that make up the core product experience, and a WordPress plugin that puts the data in front of real site visitors. This section is a deep, honest walkthrough of how it’s built — the architecture, the trade-offs, and the automation — for anyone who wants to see the engineering behind the product.

System overview

Section titled “System overview”
graph LR
A[Congress.gov API] -->|sync| B["cd-etl\nAirflow DAGs"]
B -->|embed bills| I["AWS Bedrock\nTitan Embeddings"]
B --> C[("PostgreSQL + pgvector\nmembers · bills · votes")]
C --> D["cd-api\nFastAPI on Lambda"]
D -->|embed query| I
C -->|customer data| H["cd-server\napp backend"]
D -->|x-api-key| E["cd-lookup\nWordPress plugin"]
D -->|Lambda invoke| H
H --> G["cd-webapp\nReact"]
E --> F[Site visitor]
G --> F

style A fill:#eef3fa,stroke:#27619c
style B fill:#eef3fa,stroke:#27619c
style C fill:#cfe0f2,stroke:#0a2246
style D fill:#eef3fa,stroke:#27619c
style E fill:#eef3fa,stroke:#27619c
style F fill:#ffffff,stroke:#8ba0bd
style G fill:#eef3fa,stroke:#27619c
style H fill:#eef3fa,stroke:#27619c
style I fill:#eef3fa,stroke:#27619c

The repos

Section titled “The repos”

CivicDog is split across five repositories, each with a single responsibility:

Repo What it is
cd-webapp The React web app at app.civicdog.com — the core product
cd-platform Python monorepo: cd-etl (Airflow ETL) + cd-api (FastAPI, deployed on Lambda) + cd-server (app backend for cd-webapp)
cd-lookup The WordPress plugin that consumes cd-api
cd-infra Terraform for every AWS resource this stack runs on
cd-website The civicdog.com landing page and this docs site

Where to go next

Section titled “Where to go next”
  • Architecture — the repo map, the single-source-of-truth data model, and the local/prod parity philosophy.
  • Data Pipeline — the Airflow DAGs that keep members, bills, and votes in sync.
  • Semantic Search — natural-language search over legislation: tiered exact-match / similarity-fallback retrieval and the embedding pipeline behind it.
  • API — cd-api’s design: quick facts, a live OpenAPI reference, and its Lambda deployment.
  • Web App & Backend — cd-webapp and its GraphQL backend cd-server: Cognito auth, composed queries, and RAG-based AI voting-record summaries with daily caps.
  • Infrastructure — the Terraform-managed AWS stack, security posture, and cost trade-offs.
  • CI/CD & Automation — keyless deploys, container automation, and IaC scanning.
  • WordPress Plugin — how cd-lookup caches, sanitizes, and tests itself.