How semani01/maieutic works
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: App.jsx Study workspace · index.js API router · supabaseWithAuth.js Supabase course data · upload.js Ingestion endpoint
Components 33
Student experience
- Study workspace
client/src/App.jsx - Authentication
client/src/hooks/useAuth.js - Socratic chat
client/src/components/ChatPanel.jsx - Chat state
client/src/hooks/useChat.js - Material upload
client/src/components/FileUpload.jsx
Course learning
- Knowledge portfolio
client/src/components/KnowledgePortfolio.jsx - Topic rooms
client/src/components/TopicRoom.jsx - Quiz mode
client/src/components/QuizMode.jsx - Topic services
server/src/routes/topics.js - Topic room service
server/src/routes/topicRoom.js - Quiz services
server/src/routes/quiz.js
Study progress
- Study sessions
client/src/components/StudySessionModal.jsx - Session summary
client/src/components/SessionSummaryPanel.jsx - Quests
client/src/components/QuestPanel.jsx - Side quests
client/src/components/SideQuestPanel.jsx - Focus timer
client/src/components/FocusTimer.jsx - Progress & rewards
client/src/components/Achievements.jsx - Session services
server/src/routes/studySessions.js - Quest services
server/src/routes/quests.js - Side-quest service
server/src/routes/sideQuests.js - XP & achievements
server/src/routes/xp.js
Tutor services
- Supabase Auth
- API router
server/src/index.js - Chat endpoint
server/src/routes/chat.js - Claude AI
- Conversation storage
server/src/routes/conversations.js - Supabase course data
server/src/db/supabaseWithAuth.js
Course knowledge
- Ingestion endpoint
server/src/routes/upload.js - File parsing
server/src/lib/parser.js - Text chunking
server/src/lib/chunker.js - Text embeddings
server/src/lib/embeddings.js - Passage retrieval
server/src/lib/retrieval.js
Other components
- Student
Connections 48
- Student → Study workspace: uses
client/src/App.jsx - Study workspace → Authentication: loads identity
client/src/App.jsx - Authentication → Supabase Auth: authenticates
client/src/hooks/useAuth.js - Study workspace → Socratic chat: renders
client/src/App.jsx - Socratic chat → Chat state: uses chat
client/src/components/ChatPanel.jsx - Chat state → Chat endpoint: sends messages
client/src/hooks/useChat.js - Chat state → Conversation storage: persists messages
client/src/hooks/useChat.js - Study workspace → Material upload: renders
client/src/App.jsx - Material upload → Ingestion endpoint: uploads materials
- API router → Ingestion endpoint: mounts
server/src/index.js - API router → Chat endpoint: mounts
server/src/index.js - API router → Conversation storage: mounts
server/src/index.js - API router → Topic services: mounts
server/src/index.js - API router → Topic room service: mounts
server/src/index.js - API router → Quiz services: mounts
server/src/index.js - API router → Session services: mounts
server/src/index.js - API router → Quest services: mounts
server/src/index.js - API router → Side-quest service: mounts
server/src/index.js - API router → XP & achievements: mounts
server/src/index.js - Ingestion endpoint → File parsing: parses files
server/src/routes/upload.js - Ingestion endpoint → Text chunking: chunks text
server/src/routes/upload.js - Ingestion endpoint → Text embeddings: embeds chunks
server/src/routes/upload.js - Ingestion endpoint → Supabase course data: stores vectors
server/src/routes/upload.js - Chat endpoint → Passage retrieval: retrieves passages
- Passage retrieval → Text embeddings: embeds query
server/src/lib/retrieval.js - Passage retrieval → Supabase course data: matches vectors
server/src/lib/retrieval.js - Chat endpoint → Claude AI: generates guidance
- Topic room service → Passage retrieval: retrieves context
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
server/src/routes/quiz.js - Session services → Supabase course data: tracks sessions
server/src/routes/studySessions.js - Session services → Claude AI: creates summaries
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
client/src/App.jsx - Study workspace → Topic rooms: renders
client/src/App.jsx - Study workspace → Quiz mode: opens quizzes
client/src/App.jsx - Study workspace → Study sessions: opens sessions
client/src/App.jsx - Study sessions → Session services: starts session
- Study workspace → Session summary: shows summary
client/src/App.jsx - Study workspace → Quests: renders
client/src/App.jsx - Study workspace → Side quests: renders
client/src/App.jsx - Study workspace → Focus timer: renders
client/src/App.jsx - Study workspace → Progress & rewards: renders
client/src/App.jsx - Knowledge portfolio → Topic services: loads topics
- Topic rooms → Topic room service: loads topic content