Socrates — AI-Powered Socratic Tutor

The AI tutor that asks questions instead of giving answers — building genuine understanding through the Socratic method.

Comment

Inspiration

Every AI tool I've seen makes students worse at learning. You type a question, you get an answer, you copy it, you forget it by morning. That's not learning — that's outsourcing thinking.

The best human tutors I've had never told me the answer. They asked me what I thought, found the exact crack in my understanding, and made me fix it myself. That experience sticks. I wanted to build that at scale.

Socrates is named after the Greek philosopher who believed knowledge comes from within — the teacher's job is to draw it out through questioning, not lecture it in. That's the product.

What It Does

Socrates is a full-stack AI tutoring platform covering 8 subjects and 85+ mapped concepts. Unlike every other AI tool, it refuses to give direct answers. Instead:

  1. Diagnostic Assessment — 5 branching questions map exactly what you already know before wasting time on things you've mastered
  2. Socratic Dialogue — The AI finds the precise gap in your understanding and asks one targeted question at a time until you discover the answer
  3. Live Knowledge Map — An interactive SVG graph shows your mastery in real time. Nodes glow from grey → amber → green as you learn
  4. Spaced Repetition Flashcards — Full SRS algorithm (4 buckets: New → Learning → Reviewing → Mastered) with 3D flip animations
  5. Pomodoro Timer — 25/5 work/break cycles with SVG progress ring built into every session
  6. Session Replay — Every past session is saved so you can re-read the full transcript
  7. AI Study Plans — Personalized 5-day plans generated from your actual knowledge gaps
  8. Teacher Dashboard — Class-wide knowledge heat maps so teachers see exactly what to re-teach tomorrow

How I Built It

No frameworks. No build tools. Pure vanilla JavaScript.

The entire app is a hash-based SPA (#/path?params) with a custom router, all rendered client-side. Data lives 100% in localStorage — nothing is sent to any server except AI calls.

AI layer: Groq's Llama 3.3 70B via a Vercel Edge Function proxy. The edge function keeps the API key server-side; visitors get full AI for free without needing their own key. Responses stream word-by-word via Server-Sent Events (SSE) for the real-time typing effect.

Knowledge graph: Custom SVG renderer with pan/zoom, force-directed-style layout, and click-to-navigate. Each subject has a prerequisite graph (e.g. "derivatives" requires "limits" requires "functions") that lights up as mastery is recorded.

CSS design system: ~1,100 lines of custom CSS variables with full dark/light mode switching, no Tailwind needed. Every color, spacing, and radius token is a CSS variable so themes flip in a single class toggle.

Challenges

The Socratic constraint is technically hard. Getting an LLM to never give a direct answer, while still being helpful and not frustrating, required careful prompt engineering. The system prompt explicitly forbids answer-giving but has nuanced rules for when to "crack" after repeated struggle (so students aren't stuck forever).

The knowledge graph layout was the hardest engineering problem. Manually positioning 85+ nodes across 8 subjects to look good and feel navigable took significant iteration.

API key security — the Groq key can't be in client-side JS. Solved with a Vercel Edge Function proxy that forwards requests server-side. GitHub push protection caught an accidental commit and blocked it.

Performance at load — the window.load event was blocked by external CDN scripts (GSAP, fonts), causing a blank screen on slower connections. Fixed by switching to DOMContentLoaded + async CDN scripts + CSS animation fallbacks so content appears even before GSAP loads.

What I Learned

  • The Socratic method genuinely works as an AI interaction model — it's not just a gimmick. Students who can't get a free answer are forced to think, and that thinking is the learning.
  • Vanilla JS SPAs are highly capable and much lighter than framework-based alternatives when you control the full design system.
  • Edge Functions are the right architecture for proxying third-party API keys in static sites — zero cold start, globally distributed, free tier covers most usage.
  • Spaced repetition is deceptively simple to implement but the UX around it (making the rating feel natural, showing progress clearly) is where all the work is.

Built With

Share this project:

Updates

Submission history