# khush2006b/socratic-tutor architecture

> Architecture diagram of the GitHub repository khush2006b/socratic-tutor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khush2006b/socratic-tutor
- Repository: https://github.com/khush2006b/socratic-tutor

## Overview

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: [`backend/app/main.py`](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/tutor.py`](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/tutor.py) (Tutor stream API), [`frontend/src/components/TutorChat.jsx`](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/TutorChat.jsx) (Tutor chat), [`backend/app/routers/sessions.py`](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/sessions.py) (Session API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Student experience"]
  node_workspace["Tutoring workspace<br/>[App.jsx]"]
  node_problem_ui["Problem panel<br/>[ProblemPanel.jsx]"]
  node_editor["Code editor<br/>[EditorPanel.jsx]"]
  node_chat["Tutor chat<br/>[TutorChat.jsx]"]
  node_visuals["Algorithm visualizations"]
  node_voice["Voice tutor<br/>[useVoiceTutor.js]"]
  node_session_state["Session state<br/>[sessionStore.js]"]
  node_auth_ui["Authentication state<br/>[authStore.js]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_api["API and sessions"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_problem_api["Problem parsing<br/>[problems.py]"]
  node_tutor_api["Tutor stream API<br/>[tutor.py]"]
  node_hints_api["Hint API<br/>[hints.py]"]
  node_sessions_api["Session API<br/>[sessions.py]"]
  node_notes_dash["Notes and dashboard"]
  node_models["Problem and session models"]
end

subgraph group_tutor["Tutoring intelligence"]
  node_graph["Tutor graph<br/>[nodes.py]"]
  node_hint_graph["Hint graph<br/>[hint_graph.py]"]
  node_grounding["Problem grounding<br/>[grounding.py]"]
  node_prompt["Socratic prompting<br/>[socratic_prompt.py]"]
  node_gemini["Gemini model service<br/>[gemini.py]"]
end

subgraph group_learning["Learning services"]
  node_learning_services["Adaptive learning services"]
end

subgraph group_state["Identity and persistence"]
  node_config["Application settings<br/>[config.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_session_manager["Session manager<br/>[session_manager.py]"]
  node_database["Database adapter<br/>[database.py]"]
end

node_student(("Student"))
node_supabase[("Supabase")]
node_gemini_ext{{"Gemini"}}

node_student -->|"uses"| node_workspace
node_workspace -->|"assembles"| node_problem_ui
node_workspace -->|"assembles"| node_editor
node_workspace -->|"assembles"| node_chat
node_problem_ui -->|"updates"| node_session_state
node_editor -->|"updates"| node_session_state
node_chat -->|"updates"| node_session_state
node_chat -->|"renders"| node_visuals
node_voice -->|"streams turns"| node_chat
node_voice -->|"reads state"| node_session_state
node_chat -->|"calls tutor API"| node_api_client
node_api_client -->|"gets token"| node_auth_ui
node_auth_ui -->|"authenticates"| node_student
node_api_app -->|"registers"| node_problem_api
node_api_app -->|"registers"| node_tutor_api
node_api_app -->|"registers"| node_hints_api
node_api_app -->|"registers"| node_sessions_api
node_api_app -->|"registers"| node_notes_dash
node_tutor_api -->|"runs graph"| node_graph
node_tutor_api -->|"manages session"| node_session_manager
node_tutor_api -->|"loads grounding"| node_grounding
node_hints_api -->|"runs hints"| node_hint_graph
node_graph -->|"builds prompts"| node_prompt
node_graph -->|"generates response"| node_gemini
node_graph -->|"persists data"| node_session_manager
node_grounding -->|"extracts knowledge"| node_gemini
node_gemini -->|"calls"| node_gemini_ext
node_sessions_api -->|"updates sessions"| node_session_manager
node_sessions_api -->|"updates profile"| node_learning_services
node_session_manager -->|"reads and writes"| node_database
node_database -->|"connects"| node_supabase
node_auth -.->|"verifies tokens"| node_supabase
node_database -->|"reads settings"| node_config
node_api_app -->|"loads settings"| node_config
node_tutor_api -->|"validates requests"| node_models
node_sessions_api -->|"validates reflection"| node_models
node_student -.->|"submits problem"| node_problem_api
node_problem_api -.->|"grounds problem"| node_grounding
node_student -.->|"requests hint"| node_hints_api
node_student -->|"reflects"| node_sessions_api
node_student -.->|"views progress"| node_notes_dash
node_learning_services -.->|"stores learning data"| node_supabase

click node_workspace "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/App.jsx"
click node_problem_ui "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/ProblemPanel.jsx"
click node_editor "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/EditorPanel.jsx"
click node_chat "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/TutorChat.jsx"
click node_visuals "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/VisualizationPanel.jsx"
click node_voice "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/hooks/useVoiceTutor.js"
click node_session_state "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/store/sessionStore.js"
click node_auth_ui "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/store/authStore.js"
click node_api_client "https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/api/client.js"
click node_api_app "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/main.py"
click node_problem_api "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/problems.py"
click node_tutor_api "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/tutor.py"
click node_hints_api "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/hints.py"
click node_sessions_api "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/sessions.py"
click node_notes_dash "https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/routers"
click node_graph "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/graph/nodes.py"
click node_hint_graph "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/graph/hint_graph.py"
click node_grounding "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/grounding.py"
click node_prompt "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/socratic_prompt.py"
click node_gemini "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/gemini.py"
click node_learning_services "https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/services"
click node_models "https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/models"
click node_config "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/config.py"
click node_auth "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/middleware/auth.py"
click node_session_manager "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/session_manager.py"
click node_database "https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace,node_problem_ui,node_editor,node_chat,node_visuals,node_voice,node_session_state,node_auth_ui,node_api_client toneBlue
class node_api_app,node_problem_api,node_tutor_api,node_hints_api,node_sessions_api,node_notes_dash,node_models,node_supabase toneAmber
class node_graph,node_hint_graph,node_grounding,node_prompt,node_gemini toneMint
class node_learning_services toneRose
class node_config,node_auth,node_session_manager,node_database,node_student,node_gemini_ext toneIndigo
```

## Components

### Student experience

- [Tutoring workspace](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Problem panel](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/ProblemPanel.jsx): `frontend/src/components/ProblemPanel.jsx`
- [Code editor](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/EditorPanel.jsx): `frontend/src/components/EditorPanel.jsx`
- [Tutor chat](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/TutorChat.jsx): `frontend/src/components/TutorChat.jsx`
- [Algorithm visualizations](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/components/VisualizationPanel.jsx): `frontend/src/components/VisualizationPanel.jsx`
- [Voice tutor](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/hooks/useVoiceTutor.js): `frontend/src/hooks/useVoiceTutor.js`
- [Session state](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/store/sessionStore.js): `frontend/src/store/sessionStore.js`
- [Authentication state](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`
- [API client](https://github.com/khush2006b/socratic-tutor/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and sessions

- [FastAPI application](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/main.py): `backend/app/main.py`
- [Problem parsing](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/problems.py): `backend/app/routers/problems.py`
- [Tutor stream API](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/tutor.py): `backend/app/routers/tutor.py`
- [Hint API](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/hints.py): `backend/app/routers/hints.py`
- [Session API](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/routers/sessions.py): `backend/app/routers/sessions.py`
- [Notes and dashboard](https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/routers): `backend/app/routers`
- [Problem and session models](https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/models): `backend/app/models`

### Tutoring intelligence

- [Tutor graph](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/graph/nodes.py): `backend/app/graph/nodes.py`
- [Hint graph](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/graph/hint_graph.py): `backend/app/graph/hint_graph.py`
- [Problem grounding](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/grounding.py): `backend/app/services/grounding.py`
- [Socratic prompting](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/socratic_prompt.py): `backend/app/services/socratic_prompt.py`
- [Gemini model service](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/gemini.py): `backend/app/services/gemini.py`

### Learning services

- [Adaptive learning services](https://github.com/khush2006b/socratic-tutor/tree/main/backend/app/services): `backend/app/services`

### Identity and persistence

- [Application settings](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/config.py): `backend/app/config.py`
- [JWT authentication](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/middleware/auth.py): `backend/app/middleware/auth.py`
- [Session manager](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/session_manager.py): `backend/app/services/session_manager.py`
- [Database adapter](https://github.com/khush2006b/socratic-tutor/blob/main/backend/app/services/database.py): `backend/app/services/database.py`

### Other components

- **Student**
- **Supabase**
- **Gemini**

## Connections

- Student → Tutoring workspace: uses
- Tutoring workspace → Problem panel: assembles (evidence: `frontend/src/App.jsx`)
- Tutoring workspace → Code editor: assembles (evidence: `frontend/src/App.jsx`)
- Tutoring workspace → Tutor chat: assembles (evidence: `frontend/src/App.jsx`)
- Problem panel → Session state: updates (evidence: `frontend/src/components/ProblemPanel.jsx`)
- Code editor → Session state: updates (evidence: `frontend/src/components/EditorPanel.jsx`)
- Tutor chat → Session state: updates (evidence: `frontend/src/components/TutorChat.jsx`)
- Tutor chat → Algorithm visualizations: renders (evidence: `frontend/src/components/TutorChat.jsx`)
- Voice tutor → Tutor chat: streams turns (evidence: `frontend/src/hooks/useVoiceTutor.js`)
- Voice tutor → Session state: reads state (evidence: `frontend/src/hooks/useVoiceTutor.js`)
- Tutor chat → API client: calls tutor API
- API client → Authentication state: gets token (evidence: `frontend/src/api/client.js`)
- Authentication state → Student: authenticates (evidence: `frontend/src/store/authStore.js`)
- FastAPI application → Problem parsing: registers (evidence: `backend/app/main.py`)
- FastAPI application → Tutor stream API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Hint API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Session API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Notes and dashboard: registers (evidence: `backend/app/main.py`)
- Tutor stream API → Tutor graph: runs graph (evidence: `backend/app/routers/tutor.py`)
- Tutor stream API → Session manager: manages session (evidence: `backend/app/routers/tutor.py`)
- Tutor stream API → Problem grounding: loads grounding (evidence: `backend/app/routers/tutor.py`)
- Hint API → Hint graph: runs hints (evidence: `backend/app/routers/hints.py`)
- Tutor graph → Socratic prompting: builds prompts (evidence: `backend/app/graph/nodes.py`)
- Tutor graph → Gemini model service: generates response (evidence: `backend/app/graph/nodes.py`)
- Tutor graph → Session manager: persists data (evidence: `backend/app/graph/nodes.py`)
- Problem grounding → Gemini model service: extracts knowledge
- Gemini model service → Gemini: calls (evidence: `backend/app/services/gemini.py`)
- Session API → Session manager: updates sessions (evidence: `backend/app/routers/sessions.py`)
- Session API → Adaptive learning services: updates profile (evidence: `backend/app/routers/sessions.py`)
- Session manager → Database adapter: reads and writes (evidence: `backend/app/services/session_manager.py`)
- Database adapter → Supabase: connects (evidence: `backend/app/services/database.py`)
- JWT authentication → Supabase: verifies tokens
- Database adapter → Application settings: reads settings (evidence: `backend/app/services/database.py`)
- FastAPI application → Application settings: loads settings (evidence: `backend/app/main.py`)
- Tutor stream API → Problem and session models: validates requests (evidence: `backend/app/routers/tutor.py`)
- Session API → Problem and session models: validates reflection (evidence: `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 (evidence: `backend/app/routers/sessions.py`)
- Student → Notes and dashboard: views progress
- Adaptive learning services → Supabase: stores learning data