Loading…
K53 Drill Master
An offline-first K53 learner's-licence drill PWA, 2,195 answerable questions across 26 drill modes in English, Afrikaans and isiXhosa, built for budget Android on 3G.
View the product page- Data model
- 1 Supabase table + ~15 localStorage stores
- Stack
- 9 technologies
- Provenance
- real build journals
The problem
SA's K53 failure rate exceeds 60%, people fail on never having seen the question format under timed pressure, not on knowledge. Existing options (out-of-stock booklets, 15–40MB government PDFs, a 2009 quiz site) all fail the budget-device, prepaid-data user.
.jpg&w=3840&q=75)
Architecture
How it’s wired
A container-level view of the real system, the boundaries, the trust edges, and where intelligence and money actually flow.
A routerless client SPA: all learning state lives in localStorage (including the SM-2 schedule), so the app works fully offline. Supabase only handles magic-link auth and the PayFast-ITN subscriber activation.
.jpg&w=3840&q=75)
By the numbers
~107KB
index JS (gzip) · 180KB full
100
Lighthouse PWA & SEO
2,195
questions · 1,249 authored + 946 generated
R0.54
AI cost / month @ 10k calls
Stack
React 18 + Vite (repo pins v8)Framer MotionSupabase (auth + Edge Functions)OpenAI gpt-4o-mini (via Edge Function)vite-plugin-pwa (Workbox)Capacitor 8 (Android)PayFast (one-time)Paystack (recurring)Vercel Analytics
Intelligence
The AI Tutor runs OpenAI gpt-4o-mini, a deliberate, honest exception to the platform’s Anthropic default (it shows range). The key lives server-side in a Supabase Edge Function (ai-explain), never in the client; the browser keeps a djb2-hashed localStorage cache (200 entries), allows 3 free calls a day, and deducts quota only on a successful reply. Temperature 0 makes repeat questions deterministic, so cache hits keep cost near R0.54/month at 10k calls.
Data model
1 Supabase table + ~15 localStorage stores
- subscribers, id, user_id (FK auth.users), email, plan (CHECK monthly | bundle | lifetime | lifetime_pdp | group), status, payfast_payment_id, expires_at
- RLS: read_own (auth.uid() = user_id) + service_insert (service-role only), "the anon key is public, and it doesn’t matter, because the DB says no"
- two independent learning engines in localStorage: k53_sr_v1 (SM-2) and the Nervous System (k53_nerve_mastery_v1 / k53_xp_v1), plus freemium, streak, history and prefs keys
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
Two payment gateways, split by cadence, verified server-side
- Context
- Monthly subscriptions and one-time lifetime unlocks have different billing needs on ZAR rails.
- Decision
- Monthly → Paystack recurring (a webhook activates/extends by email on charge.success and cancels on subscription.disable); bundle and lifetime → PayFast one-time. Both settle through an internal finance hub that validates the ITN before anything is activated.
- Consequence
- Native ZAR billing for both models, with payment truth never trusted to the browser.
ADR-02
AI economics moved server-side
- Context
- An API key must never ship in a client bundle, and each explanation must cost almost nothing.
- Decision
- The tutor calls a Supabase Edge Function (ai-explain) that holds the key in secrets; the client caches answers (djb2 localStorage, 200 entries), allows 3 free calls/day, and deducts quota only on success. Temperature 0 makes repeats deterministic.
- Consequence
- No exposed key, and near-100% cache hits on repeated questions.
ADR-03
A quantified zero-library posture
- Context
- Every kilobyte matters on a prepaid 3G budget device.
- Decision
- No React Router (a routerless state machine; back handled by pushState/popstate on web and the Capacitor backButton on native; ~50KB saved), no i18n library (a hand-rolled 648-line i18n across 3 languages; ~40KB saved), no state manager, zero audio files (Web Audio synth).
- Consequence
- "Every number is a decision", a ~107KB index chunk that runs fully offline.
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
Two independent learning engines
SM-2 spaced repetition schedules review (interval ladder 1d → 6d → round(interval × EF); "mastered" at ≥21 days) while a separate "K53 Nervous System", ~230 lines of dependency-free JS, runs a 6-node hexagon of "nerves," an XP model with combo bonuses and a 6-level ladder (Learner → Traffic Officer, 0 → 15,000 XP) with time-decaying health. Every answer is recorded into both.
02
A signed token that can’t buy premium on its own
Checkout mints an HMAC-SHA256 unlock token, but verification also demands a subscribers row written only by the server-to-server PayFast ITN handler, closing the "return_url token = free premium" hole. The client polls verify up to 12× over ~30s to absorb the redirect-vs-ITN race.
03
One React codebase, two runtimes
The same app ships as a web PWA and a native Android build, runtime-forking auth (PKCE + a za.co.k53drillmaster:// custom scheme, exchanged on the Capacitor appUrlOpen event) and payments (opened in the system browser; the ITN activates regardless), with the Capacitor build stripping the service worker so the webview never fights Workbox.
Sourced from nanda-k53-drill-master, BUILDLOG_k53, WONDERLAND_DECISIONS_K53, masteryStore.js, spacedRepetition.js, api/{itn,verify,paystack-webhook}.js.
.jpg&w=3840&q=75)
Keep exploring