Notes
Things that were harder than they looked.
Short engineering notes taken out of the products on this site — the decision, why the obvious version was wrong, and what it cost. Each one links to the case study where the full walk-through lives.
These are working notes rather than tutorials. They are specific to the codebase they came from, and most of them are lessons I only learned because the first attempt shipped.
PaymentsFrom the Belka case study
If the client can write the entitlement, the entitlement is not real
Belka’s paid level unlocks were originally written by the app. Because
user_level_access carried a client INSERT policy, any signed-up user could insert a row and grant themselves every paid level; a second hole let a promo row with a NULL level unlock anything. The fix was not better client code — it was deleting the client’s write path entirely. Grants now come only from an HMAC-verified checkout.paid webhook, or from a SECURITY DEFINER function that validates, burns and grants a promo code inside one transaction.Read the case study →
PaymentsFrom the Belka case study
Reconciling a payment the phone never sees
The learner pays in an external browser and the grant reaches Supabase over a channel the app is not part of. The app can come back to the foreground before, during or after the webhook lands, and on Android may be cold-launched by the deep link. Three independent re-entry detectors — a warm
Linking listener, getInitialURL() for a cold launch, and an AppState transition for the user who just taps back — all converge on one idempotent verification routine that polls for the server-written grant rather than trusting the processor’s word.Read the case study →
MoneyFrom the Al Burhan case study
Store money as integers, and never let a row be edited
Al Burhan keeps cash balances for four branches. Amounts are integer centimes, never floats. The ledger is append-only: a correction is a new compensating entry, not an UPDATE, so the history of a drawer is always reconstructable. Every financial write carries a client-generated UUID as an idempotency key, so a retried request after a dropped connection cannot double-count a sale. The RLS policy on the money tables grants no write at all to the client role.
Read the case study →
DataFrom the Belka case study
A parser is cheaper than 71 hand-transcriptions — and it finds your errors
Belka’s curriculum arrived as 71 Word documents in five mutually incompatible layouts, written by different people over time, with answer keys formatted six different ways. A format-sniffing Python parser turned them into ~1,931 type-checked quiz questions. The part that mattered most was not the parsing: it was discovering that the source documents’ own answer keys were sometimes wrong, and adding an override table where each correction carries a comment recording the evidence for it.
Read the case study →
MobileFrom the Belka case study
Grading speech is not string equality
A speech recognizer returns several competing hypotheses, transcribes numbers as digits, swaps homophones and adds diacritics — while a genuinely correct attempt still has to pass. Belka normalises with Unicode NFD decomposition, canonicalises known homophones through a hand-built map, then grades in tiers: exact or containment, then per-word matching, then a bounded character diff. Crucially it grades every hypothesis and keeps the best result, instead of trusting the recognizer’s top answer.
Read the case study →
ArchitectureFrom the Nawafid case study
A payment flow for a market with no card gateway
Most Algerian students cannot pay with a card. Nawafid takes CCP and BaridiMob transfers instead: the student uploads a receipt, staff approve it, and approval — not upload — is what grants enrolment and splits the commission between teacher and platform. It is slower than a gateway and it needs a human in the loop, but it is the flow that actually matches how money moves there.
Read the case study →
CostFrom the Spirex case study
Meter the AI, or the AI meters you
Spirex runs on-demand GPT-4o analyses, chart-screenshot vision and real-time voice. Each of those has a per-call cost that a motivated user will happily multiply by a thousand. The coin economy is not only a monetisation device — it is the rate limiter. Usage is metered server-side and deducted before the model call, so an expensive feature cannot outrun what the account paid for.
Read the case study →
PostgresFrom the Biggo case study
Enforce the plan in the database, not in the pricing page
Biggo sells subscription packages that cap how many listings an agency may publish. That cap lives in a Postgres trigger, not in the form that creates a listing. The UI still hides the button when the quota is spent, because that is better UX — but the database is what actually refuses the insert, and it refuses it identically whether the request came from the app, a stale tab or a curl command.
Read the case study →