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

Pitrova: what a car really costs, on one small server

What it is

Kenyan car owners log a fill-up or a service in under a minute. Pitrova adds it up: monthly spend, cost per kilometre, fuel economy from full tank to full tank, and the services and bills coming next.

Shape

A modular monolith in three processes. The browser only talks to the web app, which forwards /api/v1 to the API, so the browser sees a single origin and session cookies stay host-only.

browser -> Cloudflare -> Dokku nginx -> web  Next.js 16 · PWA
                                        |  /api/v1 forwarded
                                        v
Redis 7 <------------------------------ api  FastAPI -> R2 receipts, photos
sessions · cache · rate limits          |  defer job
                                        v
                                    Postgres 16 <-- worker  Procrastinate
                                    data + job queue
                                        |  nightly dump
                                        v
                                    R2 backups  own bucket, own keys

api, worker -- OpenTelemetry over OTLP/HTTP --> Alloy

Background jobs

Procrastinate keeps the queue in the same Postgres as the data, and the API defers a job on its own session's connection. The job row and the domain row commit together or not at all, so there is no outbox and no window where one exists without the other.

  • Tasks take IDs, not objects, and load their row first. One that finds its work already finished exits early, so running a task twice does nothing new.
  • A dead worker doesn't strand its jobs. A job every minute re-queues work whose worker has sent no heartbeat for 90 seconds.
  • Procrastinate's tables stay out of Alembic. The release phase applies the job schema first, then the app's migrations, then the worker and API restart.

Connection budget

Running out of Postgres connections fails the API and the worker at the same moment, so every pool is counted and the total has to fit under a hard ceiling:

  api processes × API_POOL_SIZE
+ workers × (WORKER_CONCURRENCY + 4 Procrastinate pool
             + 1 LISTEN + 1 healthcheck + 1 queue-depth metric)
+ 2 for migrations
<= 0.8 × max_connections

The SQLAlchemy pools have no overflow, so these are caps rather than targets, and the API never opens a Procrastinate pool of its own. The numbers live next to each other in the environment file, so changing one means seeing the others.

Sessions and rate limits

Sessions are hand-rolled rather than taken from an auth package. The browser holds an opaque ID in an HttpOnly, Secure, SameSite=Lax cookie; the session itself lives in Redis with a sliding expiry, and a per-user set makes "sign out everywhere" one delete. Passwords use Argon2id, and unsafe methods need a double-submit CSRF token.

Rate limits are a sliding window in Redis, run as one Lua script so the check and the count can't race, and a refusal returns 429 with a Retry-After header. Redis is never the source of truth for anything in the domain: losing it signs people out and resets the limits, but loses no data.

Observability

Every line of log output is one JSON object carrying the trace ID, and request lines name the route template, never the raw path, because paths can carry tokens. A redaction pass masks emails, Kenyan phone numbers, number plates and VINs, and the same rules run over span attributes. Telemetry is pushed over OTLP to Alloy, so no port is exposed, and an inbound traceparent is ignored so a client can't choose its own trace ID.

/readyz checks Postgres, Redis and object storage, each with a 2-second timeout. It reports worker freshness too, but a stale worker never fails readiness: a dead background process shouldn't pull a healthy API out of rotation.

Deploy

git push dokku main. The release phase creates the job schema and runs Alembic before the worker and API restart, so new code never meets an old schema. Database backups run nightly, encrypted, to their own R2 bucket.

# apps/api/Procfile
web:     uvicorn milemind.api.app:create_app --factory --no-proxy-headers …
worker:  python -m milemind.jobs.worker
release: python -m milemind.jobs.schema && alembic upgrade head

Decisions

shapeModular monolith, three processes
webPWA first; a native app waits until the product is validated
webThe web app forwards /api to the API
jobsProcrastinate on PostgreSQL for background jobs
redisRedis owns sessions, cache, rate limits and short locks, and nothing else
hostingDokku on one server, storage and backups on Cloudflare R2