<p align="center">

  <img src="docs/banner.svg" alt="Docket" width="100%">

</p>

**The unfiltered public record of what government does.**

[![License](https://img.shields.io/badge/License-Apache_2.0-E0A53B.svg)](LICENSE)

[![Next.js](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org)

[![Python](https://img.shields.io/badge/Python-3.11+-3776AB.svg)](https://python.org)

[![Status](https://img.shields.io/badge/Status-Active_Development-E0A53B.svg)](#)

---

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`](docs/NEUTRALITY.md) for the full enforceable doctrine, including CI gates.

---

## Screenshots

<table>

<tr>

<td width="50%">

**Activity feed - dark mode**

<img src="docs/screenshots/home-dark.png" alt="Docket home - dark mode" width="100%">

</td>

<td width="50%">

**Activity feed - light mode**

<img src="docs/screenshots/home-light.png" alt="Docket home - light mode" width="100%">

</td>

</tr>

<tr>

<td width="50%">

**Federal spending tracker**

<img src="docs/screenshots/spending.png" alt="Federal spending view" width="100%">

</td>

<td width="50%">

**Cross-type search**

<img src="docs/screenshots/search.png" alt="Search across bills, votes, spending" width="100%">

</td>

</tr>

</table>

---

## 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](https://api.congress.gov) | Bills, amendments, members, votes | Free api.data.gov key |

| [GovInfo API](https://api.govinfo.gov) | Full bill text, Congressional Record, public laws | Same key |

| [USAspending.gov API](https://api.usaspending.gov) | Federal awards, agency outlays | None |

| [Treasury Fiscal Data](https://fiscaldata.treasury.gov) | Debt, deficit, daily cash flows | None |

| [House Clerk XML](https://clerk.house.gov/evs/) | Roll-call votes, posted within hours | None |

| [Senate roll-call XML](https://www.senate.gov/legislative/LIS/roll_call_lists/) | Senate roll calls | None |

| [Federal Register API](https://www.federalregister.gov/api/v1) | Executive Orders, rules, notices | None |

| [LDA.gov API](https://lda.gov/api) | Lobbying disclosures (LD-1/LD-2) | Free key |

| [OpenStates v3](https://v3.openstates.org) | 50-state bill and vote data | API key (paid tier for production) |

| [LegiScan](https://legiscan.com) | State coverage supplement | API key |

| [CBO](https://cbo.gov/cost-estimates) | 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`](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`](docs/ARCHITECTURE.md)  

API contract: [`docs/API.md`](docs/API.md)  

Ingest strategy: [`docs/INGESTION_STRATEGY.md`](docs/INGESTION_STRATEGY.md)

---

## Getting Started

### Prerequisites

- Node.js 20+

- Python 3.11+

- A free [api.data.gov](https://api.data.gov) key (covers Congress.gov and GovInfo)

### 1. Clone and install

```bash

git clone https://github.com/zionboggan/docket.git

cd docket

npm install

```

### 2. Set up environment variables

```bash

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)

```bash

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

```bash

# from repo root

DOCKET_DB_PATH=./docket.db npm run dev

```

Open [http://localhost:3000](http://localhost:3000).

### 5. Run the neutrality lint

```bash

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

- [x] Federal bills, votes, members

- [x] Federal spending (USAspending + Treasury)

- [x] Executive actions (Federal Register)

- [x] Lobbying disclosures (LDA.gov)

- [x] State-level bills and votes (50 states + DC + PR)

- [x] Per-state data-confidence map

- [x] Congressional calendar and schedule

- [x] Bill version text-diff (rider/amendment detection)

- [x] Dark and light themes, mobile-first

- [x] 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`](docs/NEUTRALITY.md).

---

## License

Apache 2.0 - see [LICENSE](LICENSE).