# semani01/maieutic architecture

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

- Interactive diagram: https://gitdiagram.com/semani01/maieutic
- Repository: https://github.com/semani01/maieutic

## Overview

Maieutic is a course-aware AI study tutor. Students sign in, upload course materials, then ask Socratic questions grounded in retrieved course passages; citations and persisted conversations support learning across sessions. Separate product branches provide course/topic exploration, quizzes, structured sessions, progress tracking, and gamified study goals. The sampled source confirms authentication, chat requests, retrieval, ingestion helpers, route registration, and session-summary behavior; several documented capabilities have unsampled implementations, so their internal links are omitted rather than inferred.

Main entry points: [`client/src/App.jsx`](https://github.com/semani01/maieutic/blob/main/client/src/App.jsx) (Study workspace), [`server/src/index.js`](https://github.com/semani01/maieutic/blob/main/server/src/index.js) (API router), [`server/src/db/supabaseWithAuth.js`](https://github.com/semani01/maieutic/blob/main/server/src/db/supabaseWithAuth.js) (Supabase course data), [`server/src/routes/upload.js`](https://github.com/semani01/maieutic/blob/main/server/src/routes/upload.js) (Ingestion endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student experience"]
  node_app["Study workspace<br/>[App.jsx]"]
  node_auth["Authentication<br/>[useAuth.js]"]
  node_chatui["Socratic chat<br/>[ChatPanel.jsx]"]
  node_chathook["Chat state<br/>[useChat.js]"]
  node_uploadui["Material upload<br/>[FileUpload.jsx]"]
end

subgraph group_learning["Course learning"]
  node_topicportfolio["Knowledge portfolio"]
  node_topicroom["Topic rooms<br/>[TopicRoom.jsx]"]
  node_quizui["Quiz mode<br/>[QuizMode.jsx]"]
  node_topicsroute["Topic services<br/>[topics.js]"]
  node_topicroute["Topic room service<br/>[topicRoom.js]"]
  node_quizroute["Quiz services<br/>[quiz.js]"]
end

subgraph group_study["Study progress"]
  node_sessionsui["Study sessions"]
  node_summaryui["Session summary"]
  node_questsui["Quests<br/>[QuestPanel.jsx]"]
  node_sidequests["Side quests<br/>[SideQuestPanel.jsx]"]
  node_timer["Focus timer<br/>[FocusTimer.jsx]"]
  node_progressui["Progress &amp; rewards<br/>[Achievements.jsx]"]
  node_sessionroute["Session services<br/>[studySessions.js]"]
  node_questsroute["Quest services<br/>[quests.js]"]
  node_sidequestroute["Side-quest service<br/>[sideQuests.js]"]
  node_xproute["XP &amp; achievements<br/>[xp.js]"]
end

subgraph group_backend["Tutor services"]
  node_supabaseauth[("Supabase Auth")]
  node_server["API router<br/>[index.js]"]
  node_chatroute["Chat endpoint<br/>[chat.js]"]
  node_claude["Claude AI"]
  node_conversations["Conversation storage<br/>[conversations.js]"]
  node_database[("Supabase course data")]
end

subgraph group_knowledge["Course knowledge"]
  node_uploadroute["Ingestion endpoint<br/>[upload.js]"]
  node_parser["File parsing<br/>[parser.js]"]
  node_chunker["Text chunking<br/>[chunker.js]"]
  node_embedder["Text embeddings<br/>[embeddings.js]"]
  node_retrieval["Passage retrieval<br/>[retrieval.js]"]
end

node_student(("Student"))

node_student -->|"uses"| node_app
node_app -->|"loads identity"| node_auth
node_auth -->|"authenticates"| node_supabaseauth
node_app -->|"renders"| node_chatui
node_chatui -->|"uses chat"| node_chathook
node_chathook -->|"sends messages"| node_chatroute
node_chathook -->|"persists messages"| node_conversations
node_app -->|"renders"| node_uploadui
node_uploadui -.->|"uploads materials"| node_uploadroute
node_server -->|"mounts"| node_uploadroute
node_server -->|"mounts"| node_chatroute
node_server -->|"mounts"| node_conversations
node_server -->|"mounts"| node_topicsroute
node_server -->|"mounts"| node_topicroute
node_server -->|"mounts"| node_quizroute
node_server -->|"mounts"| node_sessionroute
node_server -->|"mounts"| node_questsroute
node_server -->|"mounts"| node_sidequestroute
node_server -->|"mounts"| node_xproute
node_uploadroute -->|"parses files"| node_parser
node_uploadroute -->|"chunks text"| node_chunker
node_uploadroute -->|"embeds chunks"| node_embedder
node_uploadroute -->|"stores vectors"| node_database
node_chatroute -.->|"retrieves passages"| node_retrieval
node_retrieval -->|"embeds query"| node_embedder
node_retrieval -->|"matches vectors"| node_database
node_chatroute -.->|"generates guidance"| node_claude
node_topicroute -->|"retrieves context"| node_retrieval
node_chatroute -.->|"stores interactions"| node_database
node_topicsroute -.->|"reads topics"| node_database
node_quizroute -.->|"reads course data"| node_database
node_sessionroute -->|"tracks sessions"| node_database
node_sessionroute -->|"creates summaries"| node_claude
node_questsroute -.->|"manages quests"| node_database
node_sidequestroute -.->|"stores tasks"| node_database
node_xproute -.->|"tracks rewards"| node_database
node_app -->|"renders"| node_topicportfolio
node_app -->|"renders"| node_topicroom
node_app -->|"opens quizzes"| node_quizui
node_app -.->|"opens sessions"| node_sessionsui
node_sessionsui -.->|"starts session"| node_sessionroute
node_app -.->|"shows summary"| node_summaryui
node_app -.->|"renders"| node_questsui
node_app -->|"renders"| node_sidequests
node_app -->|"renders"| node_timer
node_app -->|"renders"| node_progressui
node_topicportfolio -.->|"loads topics"| node_topicsroute
node_topicroom -.->|"loads topic content"| node_topicroute

click node_app "https://github.com/semani01/maieutic/blob/main/client/src/App.jsx"
click node_auth "https://github.com/semani01/maieutic/blob/main/client/src/hooks/useAuth.js"
click node_chatui "https://github.com/semani01/maieutic/blob/main/client/src/components/ChatPanel.jsx"
click node_chathook "https://github.com/semani01/maieutic/blob/main/client/src/hooks/useChat.js"
click node_uploadui "https://github.com/semani01/maieutic/blob/main/client/src/components/FileUpload.jsx"
click node_topicportfolio "https://github.com/semani01/maieutic/blob/main/client/src/components/KnowledgePortfolio.jsx"
click node_topicroom "https://github.com/semani01/maieutic/blob/main/client/src/components/TopicRoom.jsx"
click node_quizui "https://github.com/semani01/maieutic/blob/main/client/src/components/QuizMode.jsx"
click node_sessionsui "https://github.com/semani01/maieutic/blob/main/client/src/components/StudySessionModal.jsx"
click node_summaryui "https://github.com/semani01/maieutic/blob/main/client/src/components/SessionSummaryPanel.jsx"
click node_questsui "https://github.com/semani01/maieutic/blob/main/client/src/components/QuestPanel.jsx"
click node_sidequests "https://github.com/semani01/maieutic/blob/main/client/src/components/SideQuestPanel.jsx"
click node_timer "https://github.com/semani01/maieutic/blob/main/client/src/components/FocusTimer.jsx"
click node_progressui "https://github.com/semani01/maieutic/blob/main/client/src/components/Achievements.jsx"
click node_server "https://github.com/semani01/maieutic/blob/main/server/src/index.js"
click node_uploadroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/upload.js"
click node_parser "https://github.com/semani01/maieutic/blob/main/server/src/lib/parser.js"
click node_chunker "https://github.com/semani01/maieutic/blob/main/server/src/lib/chunker.js"
click node_embedder "https://github.com/semani01/maieutic/blob/main/server/src/lib/embeddings.js"
click node_retrieval "https://github.com/semani01/maieutic/blob/main/server/src/lib/retrieval.js"
click node_chatroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/chat.js"
click node_conversations "https://github.com/semani01/maieutic/blob/main/server/src/routes/conversations.js"
click node_topicsroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/topics.js"
click node_topicroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/topicRoom.js"
click node_quizroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/quiz.js"
click node_sessionroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/studySessions.js"
click node_questsroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/quests.js"
click node_sidequestroute "https://github.com/semani01/maieutic/blob/main/server/src/routes/sideQuests.js"
click node_xproute "https://github.com/semani01/maieutic/blob/main/server/src/routes/xp.js"
click node_database "https://github.com/semani01/maieutic/blob/main/server/src/db/supabaseWithAuth.js"

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_app,node_auth,node_chatui,node_chathook,node_uploadui toneBlue
class node_topicportfolio,node_topicroom,node_quizui,node_topicsroute,node_topicroute,node_quizroute toneAmber
class node_sessionsui,node_summaryui,node_questsui,node_sidequests,node_timer,node_progressui,node_sessionroute,node_questsroute,node_sidequestroute,node_xproute toneMint
class node_supabaseauth,node_server,node_chatroute,node_claude,node_conversations,node_database toneRose
class node_uploadroute,node_parser,node_chunker,node_embedder,node_retrieval,node_student toneIndigo
```

## Components

### Student experience

- [Study workspace](https://github.com/semani01/maieutic/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Authentication](https://github.com/semani01/maieutic/blob/main/client/src/hooks/useAuth.js): `client/src/hooks/useAuth.js`
- [Socratic chat](https://github.com/semani01/maieutic/blob/main/client/src/components/ChatPanel.jsx): `client/src/components/ChatPanel.jsx`
- [Chat state](https://github.com/semani01/maieutic/blob/main/client/src/hooks/useChat.js): `client/src/hooks/useChat.js`
- [Material upload](https://github.com/semani01/maieutic/blob/main/client/src/components/FileUpload.jsx): `client/src/components/FileUpload.jsx`

### Course learning

- [Knowledge portfolio](https://github.com/semani01/maieutic/blob/main/client/src/components/KnowledgePortfolio.jsx): `client/src/components/KnowledgePortfolio.jsx`
- [Topic rooms](https://github.com/semani01/maieutic/blob/main/client/src/components/TopicRoom.jsx): `client/src/components/TopicRoom.jsx`
- [Quiz mode](https://github.com/semani01/maieutic/blob/main/client/src/components/QuizMode.jsx): `client/src/components/QuizMode.jsx`
- [Topic services](https://github.com/semani01/maieutic/blob/main/server/src/routes/topics.js): `server/src/routes/topics.js`
- [Topic room service](https://github.com/semani01/maieutic/blob/main/server/src/routes/topicRoom.js): `server/src/routes/topicRoom.js`
- [Quiz services](https://github.com/semani01/maieutic/blob/main/server/src/routes/quiz.js): `server/src/routes/quiz.js`

### Study progress

- [Study sessions](https://github.com/semani01/maieutic/blob/main/client/src/components/StudySessionModal.jsx): `client/src/components/StudySessionModal.jsx`
- [Session summary](https://github.com/semani01/maieutic/blob/main/client/src/components/SessionSummaryPanel.jsx): `client/src/components/SessionSummaryPanel.jsx`
- [Quests](https://github.com/semani01/maieutic/blob/main/client/src/components/QuestPanel.jsx): `client/src/components/QuestPanel.jsx`
- [Side quests](https://github.com/semani01/maieutic/blob/main/client/src/components/SideQuestPanel.jsx): `client/src/components/SideQuestPanel.jsx`
- [Focus timer](https://github.com/semani01/maieutic/blob/main/client/src/components/FocusTimer.jsx): `client/src/components/FocusTimer.jsx`
- [Progress & rewards](https://github.com/semani01/maieutic/blob/main/client/src/components/Achievements.jsx): `client/src/components/Achievements.jsx`
- [Session services](https://github.com/semani01/maieutic/blob/main/server/src/routes/studySessions.js): `server/src/routes/studySessions.js`
- [Quest services](https://github.com/semani01/maieutic/blob/main/server/src/routes/quests.js): `server/src/routes/quests.js`
- [Side-quest service](https://github.com/semani01/maieutic/blob/main/server/src/routes/sideQuests.js): `server/src/routes/sideQuests.js`
- [XP & achievements](https://github.com/semani01/maieutic/blob/main/server/src/routes/xp.js): `server/src/routes/xp.js`

### Tutor services

- **Supabase Auth**
- [API router](https://github.com/semani01/maieutic/blob/main/server/src/index.js): `server/src/index.js`
- [Chat endpoint](https://github.com/semani01/maieutic/blob/main/server/src/routes/chat.js): `server/src/routes/chat.js`
- **Claude AI**
- [Conversation storage](https://github.com/semani01/maieutic/blob/main/server/src/routes/conversations.js): `server/src/routes/conversations.js`
- [Supabase course data](https://github.com/semani01/maieutic/blob/main/server/src/db/supabaseWithAuth.js): `server/src/db/supabaseWithAuth.js`

### Course knowledge

- [Ingestion endpoint](https://github.com/semani01/maieutic/blob/main/server/src/routes/upload.js): `server/src/routes/upload.js`
- [File parsing](https://github.com/semani01/maieutic/blob/main/server/src/lib/parser.js): `server/src/lib/parser.js`
- [Text chunking](https://github.com/semani01/maieutic/blob/main/server/src/lib/chunker.js): `server/src/lib/chunker.js`
- [Text embeddings](https://github.com/semani01/maieutic/blob/main/server/src/lib/embeddings.js): `server/src/lib/embeddings.js`
- [Passage retrieval](https://github.com/semani01/maieutic/blob/main/server/src/lib/retrieval.js): `server/src/lib/retrieval.js`

### Other components

- **Student**

## Connections

- Student → Study workspace: uses (evidence: `client/src/App.jsx`)
- Study workspace → Authentication: loads identity (evidence: `client/src/App.jsx`)
- Authentication → Supabase Auth: authenticates (evidence: `client/src/hooks/useAuth.js`)
- Study workspace → Socratic chat: renders (evidence: `client/src/App.jsx`)
- Socratic chat → Chat state: uses chat (evidence: `client/src/components/ChatPanel.jsx`)
- Chat state → Chat endpoint: sends messages (evidence: `client/src/hooks/useChat.js`)
- Chat state → Conversation storage: persists messages (evidence: `client/src/hooks/useChat.js`)
- Study workspace → Material upload: renders (evidence: `client/src/App.jsx`)
- Material upload → Ingestion endpoint: uploads materials
- API router → Ingestion endpoint: mounts (evidence: `server/src/index.js`)
- API router → Chat endpoint: mounts (evidence: `server/src/index.js`)
- API router → Conversation storage: mounts (evidence: `server/src/index.js`)
- API router → Topic services: mounts (evidence: `server/src/index.js`)
- API router → Topic room service: mounts (evidence: `server/src/index.js`)
- API router → Quiz services: mounts (evidence: `server/src/index.js`)
- API router → Session services: mounts (evidence: `server/src/index.js`)
- API router → Quest services: mounts (evidence: `server/src/index.js`)
- API router → Side-quest service: mounts (evidence: `server/src/index.js`)
- API router → XP & achievements: mounts (evidence: `server/src/index.js`)
- Ingestion endpoint → File parsing: parses files (evidence: `server/src/routes/upload.js`)
- Ingestion endpoint → Text chunking: chunks text (evidence: `server/src/routes/upload.js`)
- Ingestion endpoint → Text embeddings: embeds chunks (evidence: `server/src/routes/upload.js`)
- Ingestion endpoint → Supabase course data: stores vectors (evidence: `server/src/routes/upload.js`)
- Chat endpoint → Passage retrieval: retrieves passages
- Passage retrieval → Text embeddings: embeds query (evidence: `server/src/lib/retrieval.js`)
- Passage retrieval → Supabase course data: matches vectors (evidence: `server/src/lib/retrieval.js`)
- Chat endpoint → Claude AI: generates guidance
- Topic room service → Passage retrieval: retrieves context (evidence: `server/src/routes/topicRoom.js`)
- Chat endpoint → Supabase course data: stores interactions
- Topic services → Supabase course data: reads topics
- Quiz services → Supabase course data: reads course data (evidence: `server/src/routes/quiz.js`)
- Session services → Supabase course data: tracks sessions (evidence: `server/src/routes/studySessions.js`)
- Session services → Claude AI: creates summaries (evidence: `server/src/routes/studySessions.js`)
- Quest services → Supabase course data: manages quests
- Side-quest service → Supabase course data: stores tasks
- XP & achievements → Supabase course data: tracks rewards
- Study workspace → Knowledge portfolio: renders (evidence: `client/src/App.jsx`)
- Study workspace → Topic rooms: renders (evidence: `client/src/App.jsx`)
- Study workspace → Quiz mode: opens quizzes (evidence: `client/src/App.jsx`)
- Study workspace → Study sessions: opens sessions (evidence: `client/src/App.jsx`)
- Study sessions → Session services: starts session
- Study workspace → Session summary: shows summary (evidence: `client/src/App.jsx`)
- Study workspace → Quests: renders (evidence: `client/src/App.jsx`)
- Study workspace → Side quests: renders (evidence: `client/src/App.jsx`)
- Study workspace → Focus timer: renders (evidence: `client/src/App.jsx`)
- Study workspace → Progress & rewards: renders (evidence: `client/src/App.jsx`)
- Knowledge portfolio → Topic services: loads topics
- Topic rooms → Topic room service: loads topic content
