Simon DiesenreiterandClaude Opus 5.5
9da5a1dc48
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>
62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# Contributing to Politrack
|
||
|
||
Thanks for helping make Austrian politics more transparent. Three principles guide every change:
|
||
|
||
1. **Every fact has a source.** No claim without evidence; the UI and the API always show it.
|
||
2. **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.
|
||
3. **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](docs/contributing/adapters.md) |
|
||
| derive facts from existing data (linking, detection) | [docs/contributing/enrichers.md](docs/contributing/enrichers.md) |
|
||
| add an API endpoint or MCP tool | [docs/contributing/api.md](docs/contributing/api.md) |
|
||
| add a page or show a new claim type in the UI | [docs/contributing/frontend.md](docs/contributing/frontend.md) |
|
||
| run or write tests | [docs/contributing/testing.md](docs/contributing/testing.md) |
|
||
| understand the design | [docs/architecture/01-design-from-scratch.md](docs/architecture/01-design-from-scratch.md), [docs/data-model.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
|
||
|
||
```bash
|
||
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](docs/contributing/adapters.md#0-before-writing-code-the-legal-checklist).
|
||
* Tests: `pytest` green; new parsers come with golden fixtures; `npm run typecheck` for frontend changes.
|
||
* Changed response models → regenerate `web/src/lib/api-types.ts` (`politrack openapi --ts …`).
|
||
* New texts in both `web/messages/de.json` and `en.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), with
|
||
`COMMENT`s 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.
|