ARCHITECTURE — Cetking Universe system design (v2, 6 Oct 2026)

How the Universe is built and why. Replaces the 3 Oct version (old bot lineup: Rocky, Arena, Guruji, Sutra — dead). Login detail lives in AUTH-CONTRACT.md, UI in DESIGN-SYSTEM.md, releases in RELEASES.md. If code and this file disagree, the code wins and this file is fixed.

1. Requirements

Functional

• Students log in once (mobile OTP or Google) and stay logged in (rolling 30-day login).
• One permanent Cetking ID, one coin wallet per person across every Cetking site.
• Six bots: Oracle (home, coins), Veda (Quant), Shabda (Verbal), Tarka (Logic & DILR), Mocky (mocks, Arena battles, leaderboard), Purva (admissions, GD-PI).
• Live centre timetable (Thane, Vashi, Dadar, Borivali, Online) from CK Backoffice.
• Admissions: exam timelines and college dates (Purva).
• Profile the student completes; coins for actions (rules pending).
• Coming: TCY mocks, DynTube videos, War Room inside Mocky, AI bot chat, per-centre views.

Non-functional

2. Components

flowchart LR
  S[Student phone / browser] -->|HTTPS| V[Vercel: Next.js 14 app<br/>cetking-platform.vercel.app]
  V -->|service key, server only| CL[(Supabase: Cetking Learn<br/>identity, students, coins,<br/>sessions, timetable)]
  S -->|anon key, read only| CA[(Supabase: Cetking One AI<br/>admissions data)]
  V -->|verify OTP proof| M[MSG91]
  V -->|Google sign-in via Supabase Auth| G[Google]
  ST[Staff] --> BO[CK Backoffice MCP] --> CL
  WP[cetking.com WordPress<br/>front door 1] --> CL
  V -.planned.-> T[TCY mocks]
  V -.planned.-> D[DynTube videos]
  V -.planned.-> W[War Room / Arena]
  V -.planned.-> L[Claude + Groq via LLM router]

3. APIs (inside the app)

All under app/api/, server-only code, JSON, Cache-Control: no-store for anything personal.

Rules: every POST checks same-origin + a custom header (x-ck-identity: 1); rate limits on OTP (per IP, per phone, per day) fail closed; error messages never reveal whether a number is registered.

4. Data model

Rule: Supabase stores. Code calculates. The LLM narrates. The LLM never writes SQL.

Access: the browser never holds the Cetking Learn key. All identity work goes through ck_identity_* database functions callable by the service role only. Row-level security on every student table.

Consistency: identity and coins are strongly consistent (single Postgres, locks per person). Timetable and admissions are read-mostly; slight delay is fine.

5. Rendering and caching

Personal data is never cached at the edge (private, no-store, Vary: Cookie).

6. Scaling

• Web tier: Vercel scales functions automatically; static pages cost nothing extra.
• Database: one Supabase Postgres is ample for thousands of students. Next steps if needed: connection pooling (already built into Supabase), read replica for leaderboards, cache hot reads (timetable for the week) at the edge for a few minutes.
• Hot spots to watch: leaderboard queries (precompute), coin balance (sum per student → keep a running total if the ledger grows large), AI chat cost (LLM router tiers: template → Groq → Claude Haiku → Sonnet).
• No sharding needed at this size.

7. Reliability

• Blue-green releases: every change on a preview branch first; live only on "go live"; Vercel Instant Rollback to any previous version (RELEASES.md).
• Bot silos: each bot owns its page folder and personality file; shared parts are the "shared kit" (login, profile, design components, LLM router, analytics, health). A bot never imports another bot's code. One bot failing shows its own in-character down message; the others keep working.
• Idempotency: OTP proofs are single-use (used_proofs); welcome coins once per person (welcome_grants); session renew can't double-swap; registration uses per-phone locks so two sites can't create two students.
• Fail closed: if rate limits or the database can't answer, login refuses rather than lets people in. "Service trouble" is reported as trouble, never as "signed out" or "0 coins".
• Observability: Vercel build + function logs; ck_identity.audit_log for login events; /api/health. Planned: Sentry for front-end errors.

8. Security (summary — full baseline in ../SECURITY.md)

• Secrets only in Vercel environment variables (Production only for identity keys).
• Session cookie __Host-ck_session: httpOnly, Secure, SameSite=Lax, random token; database keeps only its hash.
• Same-origin check on every write; OTP proof re-verified server-side with MSG91.
• Pilot switch: CK_IDENTITY_PILOT_PHONES limits login to listed numbers (removed 6 Oct 2026, login open to all).

9. Key trade-offs (decided)

10. Open items

• Admissions page reads the Cetking One AI database from the browser; move behind an API route and personalise by the student's chosen exams.
• Coins rules (1,000 at 100% profile) — waiting for Ravneet.
• Per-centre views (Thane student sees Thane) — SITE-RULES.md.
• TCY, DynTube, War Room, LLM chat — not built.
• cetking.com move to this app — plan only (SESSION-CARRYOVER.md); not moving yet.