Loading…
VarsityOS
An AI "Student Operating System" for South African students, study planning, NSFAS budgeting, wellness and careers around an AI chief-of-staff, Nova.
View the product page- Data model
- 149 tables · 391 RLS policies · 220 indexes · 88 migrations
- Stack
- 14 technologies
- Provenance
- real build journals
The problem
Brilliant students arrive at university without the tutor/advisor/mentor networks privileged students take for granted, and must operate on prepaid budget Android devices, expensive data, and Stage-8 load shedding. VarsityOS is built as resilient, low-data, offline-capable infrastructure for that student.
.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.
Standard CRUD writes go client→Supabase with RLS as the auth boundary; AI paths route through rate-limited /api handlers with an atomic quota RPC. Subscriptions are verified by an internal hub and forwarded to a hub-authenticated webhook, this app never holds a Paystack secret.
.jpg&w=3840&q=75)
By the numbers
149
tables · all under RLS
391
RLS policies · 220 indexes
132
API route handlers
11
SA languages
Stack
Next.js 14 (App Router, RSC)React 18TypeScript (strict)Supabase (Postgres + RLS)Anthropic Claude (Sonnet 4.6 + vision)ArcjetUpstash RedisInngestts-fsrs (spaced repetition)@ducanh2912/next-pwa (Workbox)Mapbox GLtesseract.js · pdf-parse · node-ical (document intelligence)next-intl (11 languages)Paystack (via internal hub)
Intelligence
Nova runs on Anthropic Claude (claude-sonnet-4-6) with two-block prompt caching, an ~8k-token SA / NSFAS / crisis knowledge base cached ephemeral, plus a small live-student block. A 10-substring crisis keyword prefilter (detectCrisis) runs before any API call, and Claude vision handles image analysis on the same route (max_tokens raised to 2048 when an image is attached).
Data model
149 tables · 391 RLS policies · 220 indexes · 88 migrations
- profiles IS the user row, its id is the auth.users PK directly, every RLS policy is auth.uid() = id, and child tables cascade on delete
- POPIA baked in: popia_consent NOT NULL + popia_consent_at, captured at signup via a Zod z.literal(true)
- history-preserving deletes, group_messages.user_id / group_tasks.assigned_to use ON DELETE SET NULL so shared history survives a member leaving
- dashboard_summary view (SECURITY INVOKER) serves a per-user aggregate in one round trip while honouring base-table RLS
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
Payments delegated to an internal subscription hub
- Context
- PayFast allows only one subscription URL, but many sibling apps need recurring billing.
- Decision
- This app holds no Paystack secret, an internal hub verifies Paystack and forwards charge.success / subscription.disable over a shared x-hub-secret; the webhook deliberately returns HTTP 500 on a DB-write failure so the hub retries.
- Consequence
- A smaller secret surface here, and at-least-once activation, a paying student’s tier always eventually flips on.
ADR-02
Two-block Claude prompt caching
- Context
- Nova needs an ~8k-token SA knowledge base on every call.
- Decision
- A cached ephemeral block (static SA / NSFAS / crisis context) + a small uncached live-student block.
- Consequence
- Cache reads cost a fraction of base, so the knowledge base is near-free after the first call while staying fresh.
ADR-03
Distributed rate limiting without library lock-in
- Context
- AI routes must throttle correctly across many serverless instances.
- Decision
- A hand-rolled Upstash REST INCR + EXPIRE NX pipeline, with a transparent in-memory fallback for local dev.
- Consequence
- Correct multi-instance limits in production, still runnable locally with no Redis.
ADR-04
Indexes added from a live-DB audit, not guesswork
- Context
- The campus feed filters and sorts modules / timetable on every dashboard load.
- Decision
- A scale-audit migration checked the live database, found only primary keys on the hot tables, and added a composite (institution, created_at DESC) index.
- Consequence
- The feed’s filter + sort is satisfied from a single index.
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
Atomic Nova quota, with no cron
try_use_nova_message(user, month_key, limit) does SELECT … FOR UPDATE so concurrent requests queue instead of racing, closing the gap where two requests both pass the cap and both call Anthropic. The monthly reset happens inside the same lock (if the stored YYYY-MM ≠ current, reset to 1), so the limit self-heals with zero scheduled job.
02
A SAST-timezone proactive engine
Eight-plus Inngest cron functions, every one pinned to Africa/Johannesburg and tuned to a student’s day, exam reminders 07:00, a morning brief 07:30, an NSFAS late-payment alert 09:00, a study-gap nudge 10:00, an attendance alert 18:00, a wellness nudge 19:00, a budget alert 20:00, and a weekly digest Sunday 20:00.
03
A context-aware cost governor
Before each Nova call the route assembles a live student context from ~11 parallel Supabase queries (tasks, exams, budget, a 7-day wellness trend, XP, grades, saved bursaries), runs detectHeavyTopic() over the last 14 messages against 14 subject keyword sets, and injects tiered usage guidance that caps power-user answers (<130 words) and redirects to free SA resources, protecting margin without a hard cutoff.
Sourced from campus-compass, README (v2), BUILD_JOURNEY_VARSITYOS, supabase/migrations (86), src/app/api/nova, src/lib/inngest.
.jpg&w=3840&q=75)
Keep exploring