visibilityspots/vonk repository overview

⁠vonk

Turns the monthly vonk PDFs of Scouts en Gidsen Tervant (scoutstervant.be) into events in a family CalDAV calendar, but only after a human has approved the changes.

⁠How it works

1. vonk poll asks the scoutstervant.be WordPress REST API for new or changed vonk posts, downloads the PDFs, converts them with pdftotext and lets Claude locate the event spans for the configured takken (plus the group-wide key dates from the jaarvonk). Dates, years and event identity are derived by plain code, not by the model.
2. The poll result is sent to the vonk service, which diffs it against the events it owns in the Baikal calendar (UID prefix vonk-, domain @vonk.visibilityspots).
3. A non-empty diff is announced through Gotify with a link to an internal approve page.
4. Only after approval in the browser does the service write the diff over CalDAV.

⁠Architecture (one image, two Nomad jobs)

Both are served from the same image: vonk serve (default command) and vonk poll. The service is reachable on the internal https entrypoint only. Without secrets it starts degraded: /health still answers 200 and vonk_degraded is 1.

⁠Local development

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest                  # default markers: no network, no API key, no Baikal

pdftotext (poppler-utils) must be installed. Opt-in test markers:

Image: podman build -t vonk:dev . then dgoss run vonk:dev (see goss.yaml).

⁠Configuration

All configuration is environment based; on the cluster it arrives through a Vault template from kv/data/services/vonk (service) and kv/data/services/vonk-poll (poll job: api_token, anthropic_api_key, takken), one path per job as the Vault policy requires. Empty values and the consul-template string <no value> count as missing.

BAIKAL_CALENDAR is the calendar collection name under calendars/<BAIKAL_USER>/, not the display name. For a calendar shared with the vonk user that is the share's UUID, which the Nomad job takes from the Vault key baikal_gezin_uri; baikal_calendar is only the display name and is not used for the path.

⁠Deploy

In short:

1. Tag a semver release; CI runs ruff and pytest, then the shared github-workflows main.yml (dgoss, multi-arch linux/amd64,linux/arm64 push to Docker Hub). Set the repository variable DOCKERHUB_REPOSITORY to vonk.
2. Seed the image into the zot registry (see the nomad-visibilityspots skill).
3. Create /volume4/nomad/data/vonk/ on the NAS, register nomad/vonk-volume.hcl.
4. Write kv/data/services/vonk and kv/data/services/vonk-poll in Vault; vonk.visibilityspots.net is covered by the internal *.visibilityspots.net wildcard.
5. Copy nomad/vonk.hcl and nomad/vonk-poll.hcl to jobs/stable/services/, set the image tag, run nomad job run.
6. Paste nomad/prometheus-vonk.rules.yml into infrastructure/prometheus.hcl as a rule template; redeploy Prometheus and check /api/v1/rules.
7. Verify with a real call (curl -H 'Host: vonk.visibilityspots.net' .../health, nomad job periodic force vonk-poll), first against vonk-test, then gezin; add the Argus entries.

⁠Privacy

The repository is public. The vonk PDFs contain names and phone numbers of leiding and are never committed (tests/fixtures/pdf/ is ignored; scripts/fetch_fixtures.py verifies sources by URL and sha256). Only redacted pdftotext output is committed. Child names live only in Vault (child_names) and are never logged or echoed in error messages.