simonandClaude Opus 5.5
583ccba31c
Initial import of Politrack, a self-hosted service that tracks Austrian politicians from federal to municipal level - roles, votes, money flows, statements, meetings, social media and legal proceedings - with every claim linked to its sources. - backend: FastAPI + Postgres/pgvector; adapter framework (fetch -> parse -> load -> enrich) with robots.txt/TDM-aware fetching, a raw-response archive for reparsing, and a claim/evidence model with corroboration - sources: Parliament, Wikidata, EU Parliament/Commission, Council of Ministers, Rechnungshof party reports and donations, procurement, RTR media transparency, political ad libraries, WKStA, news feeds, Wikipedia edits, Bluesky, Mastodon, public Telegram channels, YouTube and X (official API) - web: Next.js frontend in German and English with typed API client - mcp: MCP server for AI agents and RAG - docs: architecture, data model, sources, legal notes, Unraid deployment and contributor guides; Docker Compose setup for Unraid Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.1 KiB
3.1 KiB
Contributing to Politrack
Thanks for helping make Austrian politics more transparent. Three principles guide every change:
- Every fact has a source. No claim without evidence; the UI and the API always show it.
- Only legal access. Official APIs and open data first; robots.txt, terms of service and TDM reservations are respected – enforced by the framework, documented per source.
- Fairness. Neutral wording, the procedural stage and the presumption of innocence for legal matters, connections are not accusations, data about people only in their public role.
Where to start
| I want to … | Read |
|---|---|
| add a data source (scraper/API) | docs/contributing/adapters.md |
| derive facts from existing data (linking, detection) | docs/contributing/enrichers.md |
| add an API endpoint or MCP tool | docs/contributing/api.md |
| add a page or show a new claim type in the UI | docs/contributing/frontend.md |
| run or write tests | docs/contributing/testing.md |
| understand the design | docs/architecture/01-design-from-scratch.md, docs/data-model.md |
| add a social account or party channel | backend/config/social_accounts.yaml (comments explain the fields) |
| add a news feed | backend/config/feeds.yaml (+ a SourceSpec in sources/news.py) |
Development setup
cp .env.example .env
docker compose up -d db && docker compose run --rm migrate
# Docker Desktop on Windows: the first start of `db` takes a few minutes (fsync on a bind mount is slow).
# backend
cd backend
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
export POLITRACK_DATABASE_URL=postgresql://politrack:<password>@localhost:5433/politrack POLITRACK_RAW_DIR=./data/raw
pytest
politrack run parlament.persons --max-requests 20
politrack api # http://localhost:8000/api/docs
# frontend
cd ../web
npm install
API_INTERNAL_URL=http://localhost:8000 npm run dev
Pull requests
- One topic per PR. Explain what data and why it matters; for new sources, answer the legal checklist in adapters.md.
- Tests:
pytestgreen; new parsers come with golden fixtures;npm run typecheckfor frontend changes. - Changed response models → regenerate
web/src/lib/api-types.ts(politrack openapi --ts …). - New texts in both
web/messages/de.jsonanden.json. - Style: Python formatted/linted with
ruff(line length 110); TypeScript strict. - Schema changes: a new numbered file in
backend/migrations/(never edit an applied migration), withCOMMENTs on new tables/columns – agents read them.
Reporting errors in the data
Wrong or outdated claim? Open an issue with the claim id (shown in the API) and a source for the correction. Claims are never silently deleted: they are corrected, marked as disputed with the contradicting source, or rejected in review.