Socratic Tutor

• 

  dashboard

• 

• 

• 

  tutor session

• 

• 

• 

Inspiration

It started with a frustration that's honestly too familiar.

I was watching a younger cousin prepare for her Class 11 physics boards. She had a stack of textbooks, three different YouTube playlists open at once, and a WhatsApp group full of panicked classmates sending each other last-minute notes at 1 AM. And yet — when I asked her to explain why a capacitor stores charge the way it does, she just pointed at a formula she'd memorised:

$$Q = CV$$

She could recall it. But she couldn't feel it.

That gap between knowing a formula and genuinely understanding the concept behind it is something millions of Indian students live in every single day. Coaching centres teach to the test. YouTube videos teach the student, not with them. And most AI tools just become a fancier answer machine: you type a question, it hands you a response, and you move on without ever being pushed to think.

That's what made us think about Socrates, the ancient Greek philosopher who never once gave his students a direct answer. He asked questions. He probed. He made people uncomfortable in the most productive way possible. His method wasn't about delivering knowledge; it was about helping people discover it themselves.

We thought, 'What if an AI tutor actually did that?'

Not just a chatbot that answers questions, but one that asks them back in a thoughtful, patient, structured way until the student genuinely gets it. That was the seed of Socratic Tutor.

What it does

Socratic Tutor is an AI-powered study companion built specifically for Indian school students in classes 9 through 12 preparing for board exams, JEE, NEET, and similar high-stakes tests. Instead of handing students answers on a platter, it teaches the way the ancient philosopher Socrates did: by asking questions back, probing gaps, and making the student do the actual thinking. You type a doubt, and rather than just resolving it, the AI tutor guides you toward figuring it out yourself, which is how real understanding actually forms.

When a student starts a session, they choose their class level, stream (science, commerce, or humanities), and the subject they want to study. They can also pick their tutor's personality: Socrates, Athena, Plato, or Aristotle, each adding a slightly different flavour to the conversation. The tutor opens with a simple but deliberate question: "What do you already know about this topic?" and the dialogue builds from there. Throughout the session, the AI stays in guiding mode, never just giving away answers unless the student has genuinely wrestled with the problem first.

But the workspace is more than just a chat interface. Once a session is deep enough, students can generate structured AI study notes from the entire conversation, create a set of five flashcards on the key concepts covered, or instantly produce a board-style mock test in the CBSE, Class Test, or Unit Test format based exactly on what was discussed. Notes and test papers can be exported as PDFs, the conversation transcript can be previewed and copied in Markdown, and there's even a lo-fi ambient audio toggle for students who study better with background sound. Voice input is supported too, so students can speak their responses instead of typing.

After every session ends, the platform does something most tutoring tools skip entirely: it uses Gemini to quietly analyse the conversation and identify one to three specific concepts the student struggled with, things like "Newton's third law applied to non-contact forces" or "balancing redox equations in acidic medium", and logs them as knowledge gaps on the dashboard. This gives students a live, evolving record of exactly where their understanding is weakest, something even most human tutors don't formally track.

The dashboard is where the learning journey becomes visible over time. Students earn achievement badges as they hit milestones, completing their first session, studying five days in a row, exploring three or more distinct subjects, and setting their first academic goal. A streak counter tracks daily study consistency, and a radar chart visualises self-reported subject mastery across physics, maths, chemistry, biology, and history. Students can also set academic goals with target deadlines, and the AI generates a structured task roadmap to help them get there. A curated subject library lets returning students jump straight into a topic without going through setup again, making it fast to pick up exactly where they left off.

How we built it

We built Socratic Tutor as a full-stack TypeScript application with a React + Vite frontend and an Express.js backend running from a single Node process in development. The Express server and Vite's dev middleware share the same port, which kept the iteration loop tight and fast. Firebase Authentication handles all user identity, and every API route is protected by a custom requireAuth middleware that verifies Firebase ID tokens on the server before any data is touched. The database layer runs on Drizzle ORM, with tables for users, sessions, goals, roadmap tasks, daily check-ins, knowledge gaps, badges, and chat messages – a schema we thought through carefully early on, because a clean data model made every feature that followed much easier to build.

The intelligence of the product lives in how we talk to Google's Gemini 2.5 Flash API. Every chat message in a tutoring session is sent to Gemini with a carefully crafted system prompt that establishes the Socratic persona and instructs the model to guide rather than answer something that required far more iteration than we expected, because the default behaviour of any language model is to just be helpful and resolve the question immediately. We also wrapped every Gemini call in a retry utility that catches 503 errors and retries up to three times with a two-second delay, so a session never just silently breaks mid-conversation because of a transient API hiccup.

The session save flow is where several pieces come together. When a student exits a workspace, the server fires two separate Gemini calls in sequence: one to generate a concise natural-language summary of the session, and another to extract the specific concepts the student struggled with, returned as a structured JSON array that gets stored as named knowledge gaps. If either call fails with a bad parse, API timeout, or anything else, the session still saves cleanly with a fallback summary, because we made sure the AI enrichment was always additive and never blocking. Streak tracking is computed server-side by comparing the current date to the user's lastActiveDate, with a Math.round on the millisecond difference to avoid floating-point drift that would otherwise silently break someone's streak at midnight. Badges are checked and awarded automatically after each session or check-in, scanning the user's full session history against a set of predefined milestone conditions.

On the frontend, the Workspace component manages a surprisingly large amount of state: chat history, flashcard index, test generation flags, notes view mode, voice input, focus audio, PDF export, and markdown preview, all orchestrated without any global state library, just React's useState and useRef. We used the Web Speech API for voice input and jsPDF for PDF generation entirely client-side, so both features work without any additional server calls.

Challenges we ran into

The hardest challenge wasn't technical; it was philosophical. Getting Gemini to genuinely not answer questions and instead guide students toward answers was far trickier than it sounds. Every large language model is trained to be helpful, which in practice means it wants to resolve your question the moment it senses confusion. Our early system prompts would hold the Socratic line for two or three turns and then cave — the moment a student said "I don't know", the AI would just explain everything. We went through a lot of prompt iterations, testing it ourselves as if we were actual students, before landing on a formulation that stays in guiding mode consistently without feeling robotic or evasive.

Firebase ID tokens expire after one hour, which created a subtle but painful bug during long study sessions. API calls would silently start failing halfway through a session with a 401, and students had no idea why the tutor stopped responding. We fixed this by ensuring the frontend always calls getIdToken() fresh before every API request. Firebase handles the refresh automatically under the hood, but it wasn't obvious at first that this was the root cause, and tracking it down cost us a few hours.

The knowledge gap extraction feature looked simple on paper but turned out to be fragile in practice. Gemini was supposed to return a clean JSON array of objects, but it would occasionally wrap the output in markdown code fences, or return a single object instead of an array, or include trailing commentary after the JSON. We had to wrap every parse in a try-catch and normalise whatever came back, stripping fences, checking for arrays, and falling back to an empty array before we could trust it enough to actually write to the database.

Streak logic also had more edge cases than we anticipated. The core question, 'Did you study today?' sounds binary, but the moment you introduce time zones, it gets complicated. Our server runs in UTC, our users are in IST, which is UTC+5:30, and JavaScript's Date arithmetic in milliseconds has just enough floating-point imprecision to occasionally land on 0.9999 days instead of 1. We normalised all dates to midnight and used Math.round instead of a strict comparison, which fixed the issue, but it was the kind of bug that's completely invisible until it resets someone's two-week streak at 12:03 AM and they wake up furious.

Accomplishments that we're proud of

Honestly, the thing we're most proud of is that the Socratic method actually works in the product. It sounds obvious it's in the name, but making an AI that genuinely refuses to hand you answers and does it in a way that feels encouraging rather than frustrating is something we weren't sure we'd pull off. When we tested it ourselves and caught ourselves actually thinking harder because the tutor pushed back, that felt like a real win. It's not just a chatbot with a different skin; it behaves differently in a way that matters.

We're also proud of how complete the workspace feels. In a hackathon timeline, it's easy to build one feature and call it done but the workspace shipped with Socratic chat, AI-generated notes, flashcards, mock tests, PDF export, voice input, focus audio, a learning checklist, and a conversation transcript preview all working together. None of them feel bolted on. They all emerge naturally from the same tutoring session, which is exactly what we wanted.

The knowledge gap detection is probably the feature we're most quietly proud of. It's not flashy, but it's genuinely useful in a way that most edtech tools skip. The idea that after every session, the system automatically knows specifically where you're weak not just "you need to study more Physics" but "you struggled with Newton's third law applied to non-contact forces" feels like something a really attentive human tutor would do. We built it, it worked first try on the AI side, and seeing those gap cards populate on the dashboard after a real session was a genuinely satisfying moment.

And finally, we're proud that it's built for India. The class levels, the streams, the board exam targeting, the CBSE alignment none of it is an afterthought. This isn't a generic AI tutor with "India" slapped on the landing page. The entire product is shaped around how Indian students actually study, what exams they're preparing for, and what kind of pressure they're under. That specificity, we think, is what gives it a real shot at being something students would actually come back to.

What we learned

Honestly? A lot of things we didn't expect to learn.

1. Prompt engineering is its own craft. Getting Gemini to not just answer questions was harder than it sounds. Our first few system prompts would just give in the moment a student seemed confused. We had to explicitly instruct the model to stay in "guiding mode" and even then, we had to iterate a dozen times to find the right balance between being helpful and being challenging.

2. Retry logic saves lives (or at least, sessions). The Gemini API occasionally returns a 503. In a tutoring session, mid-thought, that's a terrible experience. We built a generateContentWithRetry wrapper with configurable retries and a 2-second delay that made a noticeable difference in session reliability.

3. Knowledge gap detection is surprisingly powerful. The idea of automatically extracting what a student struggled with and storing it felt academic on paper. But when we saw it working in practice, flagging "Newton's third law applied to non-contact forces" after a session, it felt like something genuinely useful. That's the kind of insight a good human tutor would give you at the end of a lesson.

4. Streaks are motivating in a way that's hard to fake. We debated whether to add gamification. We're glad we did. The streak counter, combined with daily check-ins and badges, added a surprising stickiness to the product. Students wanted to come back so as not to break the streak.

5. The database schema matters from day one. We spent time early designing the relations between users, sessions, goals, roadmapTasks, userBadges, knowledgeGaps, and dailyCheckins. That upfront thinking paid off adding features mid-build was far less painful because the data model was already clean.

What's next for Socratic Tutor

The foundation is solid. But there's so much more we want to build:

Voice-first tutoring mode - full STT/TTS loop so students can have a hands-free Socratic conversation Parent dashboard - weekly progress reports sent via email, with streak summaries and knowledge gap highlights Curriculum alignment - NCERT chapter-by-chapter topic mapping so the AI knows exactly what content is expected for a student's board Peer challenges - timed head-to-head Socratic debates between students on the same topic Offline mode - cached sessions and notes accessible without internet, critical for Tier-2/Tier-3 India

Built With

• adaptive-learning
• ai-tutor
• cbse
• drizzle-orm
• edtech
• express.js
• firebase
• firebase-authentication
• full-stack
• gamification
• gemini
• generative-ai
• google-ai
• jspdf
• large-language-models
• node.js
• personalized-learning
• prompt-engineering
• react
• socratic-method
• sqlite
• tailwind-css
• typescript
• vibe
• web-speech-api