Dag daar, internetbewoner!

Hier volgt een korte uitleg over de codebase voor project in ontwikkeling: WieZeiWat (werktitel).

Wat je nodig hebt

Drie dingen op je machine, voordat je begint:

• Docker - hierin draait de PostgreSQL-database.
• uv - hiermee draait de Python-backend.
• Node (met npm) - hiermee draait de Svelte-frontend.

En een CSV-tje, waarover verderop meer.

Over uv

uv is de packagemanager van de backend. Hij leest backend/pyproject.toml (welke packages) en backend/uv.lock (welke exacte versies) en bouwt daar een virtuele omgeving van.

Het prettige eraan: je hoeft die omgeving niet zelf te maken en niet te activeren. Zet uv run voor je commando en uv regelt het - hij installeert onderweg wat er nog mist en draait je commando dan binnen de juiste omgeving. Dus uv run uvicorn ... in plaats van eerst source .venv/bin/activate.

Wel dit: elk uv run-commando moet je vanuit de map backend/ draaien. Daar staat het pyproject.toml, en zonder dat bestand weet uv niet welk project je bedoelt.

.env.example

Maak eerst een kopietje van .env.example naar .env en vul deze in. Die .env hoort in de root van de repo te staan, niet in backend/, zowel Docker als de Python-code zoekt hem daar.

De specificaties bepaal je zelf. Let alleen op DB_PORT: die staat in het voorbeeld op 5433, omdat ik lokaal al een andere PostgreSQL op de standaardpoort 5432 heb draaien. Heb jij die niet, dan mag 5432 ook prima.

De CSV

Je hebt een CSV nodig met de accountgegevens van politici. Die zit niet in deze repo en komt er ook niet in, want deze repo is openbaar.

Het bestand hoort in de root van de repo en de naam is nu nog hardgecodeerd in backend/src/wiezeiwat/seed.py. Verwacht worden in elk geval de kolommen Naam, Partij, Mastodon en Bluesky; die laatste twee bevatten de profiel-URL of zijn leeg.

Opstarten, stap voor stap

cp .env.example .env                # en invullen
make db                             # start de database-container
cd backend
uv run alembic upgrade head         # bouwt de tabellen
uv run python -m wiezeiwat.seed     # vult ze met Kamerleden en Accounts

Wat er per stap gebeurt:

make db draait docker compose up -d en start daarmee een Postgres-container. Die is op dit moment nog helemaal leeg: wel een database, geen tabellen.

alembic upgrade head draait alle migraties in backend/alembic/versions/ op volgorde, tot en met de nieuwste (head). Nu staan de tabellen er.

wiezeiwat.seed leest de CSV en zet er rijen in. Het draaien kan opnieuw: bestaande Kamerleden worden overgeslagen.

Daarna is de database klaar en kun je de boel opspinnen.

Handmatig een ophaal draaien

Een ophaalronde is één rondgang langs alle accounts in de database: posts ophalen, nieuwe opslaan. Draaien doe je zo, vanuit backend/:

uv run python -m wiezeiwat.ophalen

De -m betekent: draai deze module als script. Python zoekt wiezeiwat/ophalen.py op, importeert hem, en voert het if __name__ == "__main__"-blok onderaan uit. Dat blok roept haal_op() aan.

Wat er dan gebeurt:

1. Er komt een rij in ophaalrondes met status bezig.
2. De ronde loopt langs alle fetchers in de lijst FETCHERS in ophalen.py. Nu staat daar alleen Bluesky in; Mastodon is nog een TODO.
3. De Bluesky-fetcher pakt elk Account met platform Bluesky, haalt de laatste 100 posts op via de publieke API van Bluesky (geen inloggen nodig) en slaat elke post die er nog niet was op als Uiting. Reposts slaat hij over.
4. Gaat alles goed, dan wordt de status gelukt. Klapt een fetcher eruit, dan mislukt plus de foutmelding.

Herhalen mag: posts die al in de database staan worden overgeslagen op hun platform_post_id. Je krijgt dus geen dubbele uitingen, wel elke keer een nieuwe rij in ophaalrondes.

Wel eerst dit op orde hebben, anders draait de ronde leeg:

• de database draait (make db)
• de migraties zijn gedraaid (alembic upgrade head)
• er is geseed (wiezeiwat.seed), want zonder rijen in accounts is er niets om langs te gaan

Nakijken of het gelukt is kan met SQL in de container:

docker compose exec db psql -U <POSTGRES_USER> -d <POSTGRES_DB> \
  -c "SELECT id, status, opgehaald_op, foutmelding FROM ophaalrondes ORDER BY id DESC LIMIT 5;"

Vul bij -U en -d in wat in je .env staat. docker compose exec db draait het commando erachter binnen de draaiende db-container, dus je hebt geen psql op je eigen machine nodig.

Makefile

Er is een Makefile beschikbaar die via Docker de DB creert, de frontend opspint en de backend klaarzet.

• make db — alleen de database.
• make api — database plus backend.
• make web — alleen de frontend.
• make dev — alles tegelijk, in één terminal.

Let op dat de Makefile géén migraties draait en niet seedt. Die twee stappen hierboven doe je zelf, en na een verse clone zijn ze allebei nodig.

Let's go!