How khush2006b/socratic-tutor works
SocraticDS is an adaptive DSA tutoring product. Students authenticate, choose or submit a problem, work in an editor, and receive streamed Socratic guidance and hints; session reflections, notes, dashboard insights, and visualizations support learning across sessions. The graph follows the documented frontend-to-API-to-tutoring flow and includes problem grounding, adaptive profile features, and persistence. Several router and service implementations were not sampled, so documented capability links use the README; other uncertain call relationships are omitted.
Main entry points: main.py FastAPI application · tutor.py Tutor stream API · TutorChat.jsx Tutor chat · sessions.py Session API
Components 29
Student experience
- Tutoring workspace
frontend/src/App.jsx - Problem panel
frontend/src/components/ProblemPanel.jsx - Code editor
frontend/src/components/EditorPanel.jsx - Tutor chat
frontend/src/components/TutorChat.jsx - Algorithm visualizations
frontend/src/components/VisualizationPanel.jsx - Voice tutor
frontend/src/hooks/useVoiceTutor.js - Session state
frontend/src/store/sessionStore.js - Authentication state
frontend/src/store/authStore.js - API client
frontend/src/api/client.js
API and sessions
- FastAPI application
backend/app/main.py - Problem parsing
backend/app/routers/problems.py - Tutor stream API
backend/app/routers/tutor.py - Hint API
backend/app/routers/hints.py - Session API
backend/app/routers/sessions.py - Notes and dashboard
backend/app/routers - Problem and session models
backend/app/models
Tutoring intelligence
- Tutor graph
backend/app/graph/nodes.py - Hint graph
backend/app/graph/hint_graph.py - Problem grounding
backend/app/services/grounding.py - Socratic prompting
backend/app/services/socratic_prompt.py - Gemini model service
backend/app/services/gemini.py
Learning services
- Adaptive learning services
backend/app/services
Identity and persistence
- Application settings
backend/app/config.py - JWT authentication
backend/app/middleware/auth.py - Session manager
backend/app/services/session_manager.py - Database adapter
backend/app/services/database.py
Other components
- Student
- Supabase
- Gemini
Connections 42
- Student → Tutoring workspace: uses
- Tutoring workspace → Problem panel: assembles
frontend/src/App.jsx - Tutoring workspace → Code editor: assembles
frontend/src/App.jsx - Tutoring workspace → Tutor chat: assembles
frontend/src/App.jsx - Problem panel → Session state: updates
frontend/src/components/ProblemPanel.jsx - Code editor → Session state: updates
frontend/src/components/EditorPanel.jsx - Tutor chat → Session state: updates
frontend/src/components/TutorChat.jsx - Tutor chat → Algorithm visualizations: renders
frontend/src/components/TutorChat.jsx - Voice tutor → Tutor chat: streams turns
frontend/src/hooks/useVoiceTutor.js - Voice tutor → Session state: reads state
frontend/src/hooks/useVoiceTutor.js - Tutor chat → API client: calls tutor API
- API client → Authentication state: gets token
frontend/src/api/client.js - Authentication state → Student: authenticates
frontend/src/store/authStore.js - FastAPI application → Problem parsing: registers
backend/app/main.py - FastAPI application → Tutor stream API: registers
backend/app/main.py - FastAPI application → Hint API: registers
backend/app/main.py - FastAPI application → Session API: registers
backend/app/main.py - FastAPI application → Notes and dashboard: registers
backend/app/main.py - Tutor stream API → Tutor graph: runs graph
backend/app/routers/tutor.py - Tutor stream API → Session manager: manages session
backend/app/routers/tutor.py - Tutor stream API → Problem grounding: loads grounding
backend/app/routers/tutor.py - Hint API → Hint graph: runs hints
backend/app/routers/hints.py - Tutor graph → Socratic prompting: builds prompts
backend/app/graph/nodes.py - Tutor graph → Gemini model service: generates response
backend/app/graph/nodes.py - Tutor graph → Session manager: persists data
backend/app/graph/nodes.py - Problem grounding → Gemini model service: extracts knowledge
- Gemini model service → Gemini: calls
backend/app/services/gemini.py - Session API → Session manager: updates sessions
backend/app/routers/sessions.py - Session API → Adaptive learning services: updates profile
backend/app/routers/sessions.py - Session manager → Database adapter: reads and writes
backend/app/services/session_manager.py - Database adapter → Supabase: connects
backend/app/services/database.py - JWT authentication → Supabase: verifies tokens
- Database adapter → Application settings: reads settings
backend/app/services/database.py - FastAPI application → Application settings: loads settings
backend/app/main.py - Tutor stream API → Problem and session models: validates requests
backend/app/routers/tutor.py - Session API → Problem and session models: validates reflection
backend/app/routers/sessions.py - Student → Problem parsing: submits problem
- Problem parsing → Problem grounding: grounds problem
- Student → Hint API: requests hint
- Student → Session API: reflects
backend/app/routers/sessions.py - Student → Notes and dashboard: views progress
- Adaptive learning services → Supabase: stores learning data