Engineering at PrepAtlas

The AI tutor experiment was the part I least wanted to be a black box. A student asking “why is the answer C on this question about thermodynamics” deserves more than a confident hallucination.

The flow:

1. Chapter notes live in public.content_items, each chunked at write time and embedded with a 1536-dim model. The vector lives in a vector(1536) column alongside the chunk text.
2. When a doubt is submitted, I embed the doubt + the question text, run a cosine-similarity search on the chapter pool the student's exam covers, and take the top 5 chunks.
3. Those chunks go to Claude with a system prompt that explicitly forbids answering outside the retrieved context. The response carries citation markers that map back to topic_ids, and the UI renders them as “→ see Chapter X” links the student can open.

The real audience is a student in a Tier-2 Indian city on patchy 4G. I set myself a budget: a student should be able to complete a 30-question warm-up mock without burning more than 200 KB of data, ignoring images they choose to view.

That number drives a lot of unglamorous decisions:

• Server components by default. The test runner is a client island because it needs local state for the answer palette and timer — almost everything else is rendered on the server, ships zero JS, and hydrates only what genuinely needs interactivity.
• auth.getSession() instead of auth.getUser() in middleware. The former reads the JWT from the cookie locally; the latter hits Supabase per request. Skipping that round-trip on every navigation alone saved 100–200 ms and an unnecessary egress request. Security note: middleware uses getSession() only for the routing-layer redirect decision. Every protected page and server action re-verifies identity with getUser() (via a React-cached helper, getCachedUser) before any data access — so a forged session cookie that sneaks past the redirect still fails at the data layer.
• Immutable caching on _next/static. First mock is hot; the second mock the student takes is mostly a few KB of JSON answers.
• No third-party JS on the auth shell. No analytics, no chat widget, no webfonts loaded synchronously. The full Inter family is self-hosted from one woff2 with font-display: swap.

It is occasionally annoying — I've had to walk back a client-component implementation more than once — but the constraint forced a saner architecture than I'd have written without it.

I built the Android app as a Trusted Web Activity using Bubblewrap. The package is in.prepatlas.app and the APK is ~3 MB.

Why not React Native or a Capacitor wrap:

• One codebase, one deploy. A site push lands in the app within seconds of pm2 reload. There is no app-store-update cycle for everything that isn't the Android container itself.
• Same SSR, same server actions, same auth cookies. The TWA is Chrome pretending to be an app, so every server-side optimization on the web shows up on mobile for free.
• Honest tradeoffs. I don't have native APIs (camera, biometrics, push). When I need them — most likely for proctored mocks — I'll either add a thin Capacitor bridge or move that subset to native. The TWA covers 98% of the surface today.

The non-obvious work was Digital Asset Links: the assetlinks JSON at /.well-known/assetlinks.json is the only thing that hides Chrome's URL bar in the TWA. Get the SHA-256 fingerprint wrong and the app looks like a website. I have a release-time check that verifies the served JSON matches the production keystore.

PrepAtlas needs tens of thousands of questions across math, reasoning, general awareness, and science. A traditional CMS would have made me hand-write each one. Instead I built three feeders into the same public.questions table:

1. Template generator — Python scripts in scripts/ that produce formula-driven MCQs (e.g. percentage problems with parameterized inputs and randomized answer order). About 17k of the current pool came from here.
2. Corpus-driven generator — for general awareness and science where the answers come from a curated facts corpus. About 900 questions, fully deterministic, regenerable.
3. Sonnet-assisted batches — for the long tail, currently around 2,100 questions. A separate Claude Code session runs a generation prompt with the topic taxonomy as context, emits JSON, and a Python importer validates the schema, dedupes by hashed prompt, and upserts via the Supabase service-role key.

17k templated + 900 corpus-driven + ~2,100 Sonnet-assisted ≈ 20k total.

Every question carries a topic_id. Every topic carries an exam_id. The admin UI can override difficulty, mark items as PYQ (previous-year question), or unpublish them; everything else is generated and re-runnable. If a generator script changes, I can roll forward by regenerating that batch without touching the rest.

This is the decision I think the senior infrastructure crowd will most want to challenge, so I'll lead with the constraints.

I evaluated Pinecone, Weaviate, Qdrant, and the obvious “embed yourself” path with FAISS. The deciding factor was operational surface area: every external vector store would have meant a second source of truth, a second backup story, a second outage to monitor, and a second set of credentials in env. With pgvector:

• The vectors live in the same Postgres that has the chapter rows. A join is select chunk_text, topic_id from content_items order by embedding <=> $1 limit 5; — that's the entire retrieval call.
• RLS applies to vectors the same way it applies to every other row.
• The nightly Supabase backup includes embeddings without thinking about it.
• Adding pgvector cost me one extension install and one composite index.