● xodhiambo.com · nairobi · UTC+3 v.2026.08
xavier@nairobi:~$ cat projects/matchdesk/README.md

Matchdesk: a podcast's matchmaking desk, paid by M-Pesa

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 review for a person, never to paid.
  • 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.

MetricLabels
matchdesk_payments_totalpaid · failed · review
matchdesk_webhook_events_totalsignature valid · invalid
matchdesk_queue_depthqueue, todo · doing
matchdesk_jobs_totaltask, succeeded · failed

Decisions

paymentsPaystack over Safaricom Daraja: one integration for every host, and the platform's cut split at source
paymentsWebhooks processed in the request, not on the worker
paymentsNo refunds: a declined or expired intro becomes a credit to spend again
jobsIntros nobody answers lapse after 7 days and hand the credit back
opsRate-limit counters live in the database cache, created in the release phase