About This Guide

What this is

An internal research prototype built to demonstrate that the 2026 election data pipeline produces voter-useful information. Audience: Pavel, Nick, and coworkers reviewing data quality and the visualization approach. Not production-ready and not authorized for public distribution.

How to navigate

1. Home map — color-coded view of all 10 pipeline states. Three modes: Competitiveness (Cook ratings), Outside Spending (independent expenditure totals), Verification (data quality). Click any state to go to its race list.
2. State page — all races for a state, ordered Senate → Governor → House by district number. Each row shows the Cook rating, candidate count, and a colored dot if any data is unverified. Click a race to go to its detail page.
3. Race detail page — full candidate profiles with issue positions, voting records, recent news, endorsements, and campaign finance. The verification banner always appears first.
4. Search — type any candidate name or state abbreviation in the search bar. Results link directly to the relevant race page. Candidates in races with vacant seats are labeled.

What the verification banners mean

Every race page runs automated checks against three or more independent sources. The banner appears at the top of every race page and cannot be dismissed.

• ✓Green — All confirmed. Incumbent name, party, and filing status are consistent across all sources. Data can be relied on for voter use.
• ⚠️Yellow — Some data unverified. One or more sources returned different information. Usually minor (e.g., a name listed slightly differently between FEC and House Clerk). Expand the banner to see exactly what differs. The guide still shows the best-available data.
• 🔴Red — Significant discrepancy. Sources materially disagree (e.g., different candidates or parties listed). Verify independently with your Secretary of State before relying on this guide for this race.
• 📫Indigo — Seat vacant. The seat is empty due to death, resignation, or expulsion of the incumbent. A special election is likely pending. Candidate lists may include challengers for both the special and general elections. Verify status with your Secretary of State.

Each banner includes a collapsible "Technical details" section showing the raw values returned by each source, for internal review.

How verification works

For every race, the pipeline cross-checks incumbent information across three or more independent authoritative sources: the U.S. House Clerk's office (house.gov), GovTrack, and the Federal Election Commission. When all sources agree, the race is marked confirmed. When any source disagrees, the discrepancy is surfaced in plain English — the pipeline never silently corrects or suppresses disagreements.

Verification results are stored in a dedicated verification_status table that is never modified by the candidate research pipeline. The two pipelines are strictly separate.

Data sources

• U.S. House Clerk's office — authoritative current membership roster including vacancies
• GovTrack — member data, committee assignments, and congressional voting records
• Federal Election Commission (FEC) — candidate filings, campaign finance totals, independent expenditure reports
• Ballotpedia — candidate profiles, issue survey responses, and election calendars
• Cook Political Report — race competitiveness ratings and Cook PVI partisan index
• Sabato's Crystal Ball — independent race competitiveness ratings
• Google News RSS — recent candidate news and activity (filtered by relevance to named candidate)
• U.S. Census Bureau ACS 5-year — district demographics (Iowa only in current snapshot)

Data freshness

This portal reads from a static snapshot of the research database. Data is frozen at the time of the most recent pipeline run and does not update automatically. The snapshot covers 10 states: PA, TX, OH, NV, CO, AZ, CA, NC, GA, and IA.

Iowa has full Phase 3 research data — candidate positions, voting records, finance, endorsements, and recent news. All other states have race and candidate skeleton data, plus multi-source verification results. Research coverage for the remaining 9 states expands with each pipeline run.

To refresh: re-run the pipeline, copy the updated election_research.db to data/election_research_snapshot.db, and redeploy.

What is not yet in this guide

• Detailed candidate research (positions, voting records, finance, endorsements) for states other than Iowa
• Historical election results (back to 2012)
• Polling data
• District demographic data outside Iowa
• State legislative races
• District-level map — the current map uses state boundaries (50 shapes). A production version should use 119th Congress district boundaries (435 shapes) so each colored shape represents exactly one race. See README.md for the engineering handoff notes.