What it is
A white-label back office for a podcast's matchmaking segment, live as Make Your Move for The Porch Podcast. Listeners pay a small fee per intro with M-Pesa, the person featured reads the note and decides, and the host approves every profile before it goes up. Nobody's contact is shared until both people say yes.
Shape
One Django app in two processes. Webhooks are handled in the web request, so payments still land when the worker is down or backed up; only the emails wait for the worker.
browser -> Dokku nginx, TLS ------------> web Django · gunicorn · HTMX
Paystack -- charge.success webhook -----> |
| check signature, store event first
| emails deferred in the same commit
v
Postgres 16 data · cache · job queue
^
|
Paystack <-- verify, every minute ---- worker Procrastinate
|
v
ZeptoMail magic links · receipts
web, worker -- OTLP --> Alloy --> Tempo, Prometheus
JSON logs on stdout --> Loki
Payments
The Finder taps pay, Paystack sends an M-Pesa prompt to their phone, and they enter their PIN. Paystack only sends a webhook when a charge succeeds. There is no failure event, so a declined or abandoned payment is only ever found by asking. Two paths report an outcome, and both feed one function:
- The webhook, seconds after the PIN. The body is signed with HMAC-SHA512 and compared with
hmac.compare_digest. A bad signature gets a 401 and is never stored. - A reconcile job every minute that verifies anything still pending, which catches a lost webhook or a closed tab.
The function locks the payment row with select_for_update and does nothing if the payment is already final, so the webhook and the reconcile job agreeing on the same success is a no-op the second time. The rest follows from not losing money:
- The payment reference is generated before Paystack is called, so a crash mid-charge leaves a row to trace, not a ghost payment.
- "Paystack said no" and "we don't know" are different errors. A timeout may still end in a paid prompt, so it leaves the payment pending for verify to settle instead of marking it failed.
- The raw webhook event is saved in its own commit before processing, so it can always be read back and replayed.
- An amount or currency that doesn't match what was charged goes to
reviewfor a person, never topaid. - Amounts are whole shillings in the database and Paystack's smallest unit only at the boundary, so money never meets floating point.
Deploy
Every push to main runs CI (ruff, a missing-migration check, pytest against Postgres 16, an image build), then pushes the image to GHCR and tells Dokku to pull it. Deploys share one concurrency group, and CD skips the deploy if main has moved past the commit, so re-running an old build never replaces a newer release. Rolling back is git:from-image with an earlier SHA.
# Procfile
web: gunicorn config.wsgi --bind 0.0.0.0:8000 --workers 3 --timeout 30 …
worker: python manage.py procrastinate worker
release: python manage.py migrate --noinput && python manage.py createcachetable
The worker needs a direct Postgres connection for LISTEN/NOTIFY, so nothing like pgbouncer in transaction mode can sit in front of it. make dokku-setup provisions the app from a laptop over SSH: it reads each setting first, changes only what differs, never deletes, and never prints a secret.
Observability
Every process writes one JSON object per line, carrying the trace ID, and every response returns it as X-Request-ID, so a support question goes straight from a response to its trace in Tempo. Phone numbers and emails are masked; Paystack keys, signatures and magic-link tokens become <redacted>, in logs and span attributes alike. Telemetry is pushed over OTLP, so there is no /metrics port to expose.
| Metric | Labels |
|---|---|
matchdesk_payments_total | paid · failed · review |
matchdesk_webhook_events_total | signature valid · invalid |
matchdesk_queue_depth | queue, todo · doing |
matchdesk_jobs_total | task, succeeded · failed |