Loading…
← HandbookLive
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 pageThe 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.
Architecture
How it’s wired
Standard CRUD writes go client→Supabase with RLS as the auth boundary; AI paths route through rate-limited /api handlers. Service role is used only in the PayFast ITN webhook.
~90%
AI cost saved (caching)
~40%
smaller JS bundle (RSC)
~1.8s
LCP on weak devices
75
users
Stack
Next.js 14 (App Router, RSC)React 18TypeScript (strict)Supabase (Postgres + RLS)Anthropic ClaudeArcjetZustandts-fsrs (spaced repetition)PayFast@ducanh2912/next-pwaInngestnext-intl
AI
Nova runs on Anthropic Claude Sonnet 4.5 with two-block prompt caching and crisis detection before every call.
Data model
22 tables · RLS on all 22 · 29 indexes
- profiles (extends auth.users; subscription_tier, Nova usage counters, POPIA consent)
- nova_conversations (one row/user, JSONB history)
- expenses / income_entries (denormalised month_year for fast aggregation)
- dashboard_summary view (SECURITY INVOKER)
Key decisions
Why it’s built this way
ADR-01
App Router + RSC over Pages Router
- Context
- Fast first paint needed on weak devices and expensive data.
- Decision
- Server-side fetch + initialData hydration into a Zustand write-cache.
- Consequence
- ~40% smaller JS, no client waterfalls, LCP ~1.8s.
ADR-02
Two-block Claude prompt caching
- Context
- Nova needs an ~8k-token SA knowledge base on every call.
- Decision
- Cached ephemeral block (static SA/NSFAS/crisis context) + uncached ~400-token live student data.
- Consequence
- ~90% AI cost saving while keeping context fresh.
ADR-03
Trusted Web Activity, not a native app
- Context
- Students trust the Play Store, but a second codebase is costly.
- Decision
- Ship the PWA as a TWA verified by Digital Asset Links.
- Consequence
- Play Store presence + better push, zero billing cut, one codebase.
ADR-04
RLS from day one; service role only in the ITN webhook
- Context
- Financial + personal data must be DB-isolated even with direct client writes.
- Decision
- Every table RLS-locked; service role confined to the PayFast ITN handler.
- Consequence
- Defence-in-depth: Arcjet → middleware → Zod → RLS, no client-trusted IDs.
The hard parts, solved
Crisis safety before cost
detectCrisis runs on every message before any API call; a SADAG/LifeLine response is prepended regardless of tier or remaining quota.
Monthly message-limit integrity without cron
A server-side counter resets if nova_messages_reset_at is in a prior calendar month — checked before the tier cap, so no scheduled job is needed.
Offline / load-shedding resilience
Workbox precaches the app shell + last pages; an IndexedDB queue replays pending writes on reconnect.
Sourced from campus-compass — BUILD_JOURNEY_VARSITYOS, TECHNICAL_README, VARSITYOS_SCHEMA_AUDIT.
.jpg&w=3840&q=75)