Docket

The unfiltered public record of what government does.

---

Docket tracks federal and state legislative activity and makes it searchable for any citizen - bills, votes, amendments, riders, spending awards, executive actions, and the closed-door procedural moves that rarely make the news.

Every fact links directly to an official government record. No editorializing. No partisan framing. Just the record.

---

Neutrality Statement

Docket is deliberately and structurally non-partisan. It presents the official public record as-is. To enforce that:

• Government sources only. Every displayed fact links to an official .gov or state legislature URL. No think tanks, no news sources, no secondhand data.
• No adjectives in generated text. Numbers, names, dates, and status only. "Reduced by $X" - yes. "Slashed" or "expanded" - no. This is enforced in code via a banned-words lint that fails the build.
• Ranked by official action, not by virality. Feed ranking uses date of legislative action, dollar magnitude, and affected-population estimates from CBO or agency data - never news coverage, social shares, or editorial judgment.
• No comment sections, ever. Comments are the single largest bias-injection surface. The only user feedback allowed is a yes/no on summary clarity, never on a bill's merit.
• LLM summaries are field-extraction templates, not free-form generation. Prose summaries pull structured fields from official bill text. High-salience bills are tested against a Polarization Index before they go live.

See docs/NEUTRALITY.md for the full enforceable doctrine, including CI gates.

---

Screenshots

Activity feed - dark mode	Activity feed - light mode
Federal spending tracker	Cross-type search

---

Features

• Bills and laws - every bill introduced, its full text, sponsor, committee path, and enacted law
• Amendments and riders - text-diff view showing what was added or removed between bill versions (Introduced to Enrolled), flagging provisions inserted in appropriations or conference reports
• Votes - recorded and unrecorded - roll calls with per-member positions, and surface notices when something passed by voice vote or unanimous consent (no individual record exists - that absence is itself information)
• Executive actions - Executive Orders, proposed rules, and final rules from the Federal Register
• Federal spending - contracts, grants, agency outlays, and appropriation apportionments from USAspending.gov and Treasury Fiscal Data
• State coverage - 50 states plus DC and Puerto Rico via OpenStates and LegiScan, with an honest per-state confidence map
• Lobbying disclosures - LD-1/LD-2 filings from LDA.gov showing who lobbied which bill
• Congressional calendar and schedule - committee markups, hearings, and floor session timelines
• /how-we-pick and /who-pays - public transparency pages explaining the ranking algorithm and project funding

---

Data Sources

All primary sources are free and official. No secondhand sources appear in user-facing data.

Source	Data	Auth
Congress.gov API	Bills, amendments, members, votes	Free api.data.gov key
GovInfo API	Full bill text, Congressional Record, public laws	Same key
USAspending.gov API	Federal awards, agency outlays	None
Treasury Fiscal Data	Debt, deficit, daily cash flows	None
House Clerk XML	Roll-call votes, posted within hours	None
Senate roll-call XML	Senate roll calls	None
Federal Register API	Executive Orders, rules, notices	None
LDA.gov API	Lobbying disclosures (LD-1/LD-2)	Free key
OpenStates v3	50-state bill and vote data	API key (paid tier for production)
LegiScan	State coverage supplement	API key
CBO	Cost estimates per bill	None (scrape)

When an aggregator normalizes data (OpenStates, LegiScan), the user-facing source link always points to the underlying official government record.

See docs/DATA_SOURCES.md for the full contracts, rate limits, and change-detection strategy.

---

How It Works

Government APIs  -->  Python ingest workers  -->  SQLite
(Congress.gov,        (services/ingest/)          (docket.db)
 GovInfo,                                               |
 USAspending,                                           v
 Federal Register,                             Next.js API routes
 OpenStates, ...)                              (app/api/*)
                                                        |
                                                        v
                                             Browser (dark + light)

The ingest layer polls each source on a configurable schedule, detects changes by watermark and content-hash, and writes normalized rows to SQLite. The Next.js frontend reads its own API routes backed by better-sqlite3 - no separate API server needed for single-box deployments. Every row carries an allowlisted sourceUrl pointing to an official government endpoint; the build rejects any fact without one.

Detailed architecture: docs/ARCHITECTURE.md
API contract: docs/API.md
Ingest strategy: docs/INGESTION_STRATEGY.md

---

Getting Started

Prerequisites

• Node.js 20+
• Python 3.11+
• A free api.data.gov key (covers Congress.gov and GovInfo)

1. Clone and install

git clone https://github.com/zionboggan/docket.git
cd docket
npm install

2. Set up environment variables

cp .env.example .env
# Fill in DOCKET_CONGRESS_KEY (api.data.gov key)
# Optional: DOCKET_OPENSTATES_KEY, DOCKET_LEGISCAN_KEY, DOCKET_LEGISCAN_KEY

3. Run ingest (first-time bootstrap)

cd services/ingest
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Seed with federal data (no keys needed for GovInfo bulk path)
DOCKET_DB_PATH=../../docket.db python -m ingest.run --source bills_bulk --once
DOCKET_DB_PATH=../../docket.db python -m ingest.run --source votes_house --once

4. Run the frontend

# from repo root
DOCKET_DB_PATH=./docket.db npm run dev

Open http://localhost:3000.

5. Run the neutrality lint

npm run neutrality

This checks all generated copy, summaries, and push text against the banned-words list and confirms every fact has an allowlisted source URL.

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), React 18, Tailwind CSS
Database	SQLite via better-sqlite3
Ingest	Python 3.11+, asyncio, ARQ (Redis-backed workers)
Fonts	Archivo (display), JetBrains Mono (data labels), Fraunces (prose)
Hosting	Cloudflare Pages (frontend edge) + self-hosted ingest workers
Push	ntfy (MVP), Web Push API

---

Roadmap

• Federal bills, votes, members
• Federal spending (USAspending + Treasury)
• Executive actions (Federal Register)
• Lobbying disclosures (LDA.gov)
• State-level bills and votes (50 states + DC + PR)
• Per-state data-confidence map
• Congressional calendar and schedule
• Bill version text-diff (rider/amendment detection)
• Dark and light themes, mobile-first
• Neutrality lint in CI
• Push alerts for topic follows (policy area, agency, or member)
• Per-member voting record page
• CBO cost-estimate integration per bill
• Personalized weekly digest
• Historical trend views
• Share-as-image (factual card, no comment import)

---

Contributing

Contributions that strengthen neutrality, improve data coverage, or fix bugs are welcome.

Before opening a PR, run npm run neutrality and confirm the lint passes. Any copy that adds qualitative modifiers, assigns blame, or characterizes a bill's merit will not be merged.

See the neutrality doctrine at docs/NEUTRALITY.md.

---

License

Apache 2.0 - see LICENSE.