An adaptive DS&A tutor that learns you while you learn to code.
Bayesian Knowledge Tracing models your mastery. A contextual bandit picks your next problem. A real sandbox grades your code. Gemini explains what broke.
→ Live app · → Backend health · → Architecture · → API
Table of contents
What AdaptCode is
AdaptCode is a personalised DS&A practice platform. Most sites give every student the same next problem. AdaptCode doesn't.
Under the hood it runs two models that update on every submission:
| Model | Job | Lives in |
|---|
| Bayesian Knowledge Tracing (BKT) | Estimates the probability you actually know each concept, separately from guessing + slipping. | backend/app/services/bkt.py |
| LinUCB contextual bandit | Looks at how you've been doing (streak, error rate, time on task, current mastery) and picks a pedagogical action — easier, same, harder, redirect to a prerequisite, or hint. | backend/app/services/linucb.py |
On top of that:
- Real sandboxed execution — your code runs in Piston on an AWS EC2 node, reached only over a private Tailscale mesh. Not a public port.
- LLM post-mortems — when you fail, Gemini Flash reads your code + the failing test and writes a 3-part explanation (
what_went_wrong, why_approach_fails, concept_to_review).
- ~473 real problems across 12 concepts, seeded from a curated LeetCode-derived corpus with hidden test cases.
Live stack
| Piece | Where it lives |
|---|
| Frontend | Vercel · adapt-code.vercel.app |
| Backend | Google Cloud Run (asia-southeast1) · adaptcode-backend-…run.app |
| Sandbox | AWS EC2 (Piston via Tailscale userspace sidecar) |
| DB + Auth | Supabase (Postgres 15 + hybrid email/password + Google OAuth) |
| LLM | Google Gemini Flash (gemini-flash-latest alias) |
How it feels, in one loop
you sign up ──► diagnostic picks a starter problem
│
▼
┌────────────────────────────────────────────────┐
│ Monaco editor · hidden test cases · Submit │
└────────────────────────────────────────────────┘
│
▼
Piston runs your code → verdict + per-test diff
│
├─► BKT updates mastery P(known | observed)
├─► session_events logged (timing, errors, hints)
├─► LinUCB picks next pedagogical action
└─► if failed → Gemini drafts a 3-part explanation (async)
│
▼
next problem appears · mastery bar moves · graph lights up
Everything on the right happens in one /api/submit call. The frontend never has to orchestrate — the backend is the brain.
System architecture
flowchart LR
U[Student browser] -->|HTTPS · credentials: include| V[Vercel · Next.js 14 App Router]
V -->|httpOnly adaptcode_session cookie| CR[Cloud Run · FastAPI]
CR -->|Postgres REST + Auth| SB[(Supabase)]
CR -->|Generative Language REST| G[Gemini Flash]
CR -->|Tailscale mesh · 100.114.155.33:2000| P[AWS EC2 · Piston sandbox]
SB -.-> T1[(users / problems)]
SB -.-> T2[(sessions / events)]
SB -.-> T3[(mastery_scores)]
SB -.-> T4[(agent_state · LinUCB A, b)]
SB -.-> T5[(explanations)]
classDef edge fill:#111,stroke:#444,color:#eee
classDef cloud fill:#1a3a6c,stroke:#2b70d6,color:#fff
classDef ai fill:#4b2b74,stroke:#9c69e2,color:#fff
classDef data fill:#0e4a3a,stroke:#3fcf8e,color:#fff
class V,CR cloud
class G ai
class SB,T1,T2,T3,T4,T5 data
class U,P edge
Why this shape:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
