How suhas1010/socrates works
Socrates is a project-first AI tutor: a learner signs in, submits an AI project goal, receives an agent-built learning roadmap, diagnoses prior knowledge, approves a plan, and progresses through teaching, coding, live testing, and teach-back. The graph highlights those documented stages and the sampled agent, API, and persistence layers. Several UI and runtime connections are documented in the README but their implementation was not sampled; those relationships cite the README rather than implying source-level inspection.
Main entry points: orchestrator.ts Agent Orchestrator · LessonView.tsx Lesson and Build Views · llm.ts LLM Provider Layer · route.ts Model Review
Components 32
Learner Experience
- Learning Workspace
src/app/page.tsx - Goal Intake
src/components/LandingView.tsx - Pipeline Experience
src/components/AgentPipelineModal.tsx - Pipeline Progress
src/components/LearnerPipelineLoading.tsx - Plan Approval
src/components/PlanReviewView.tsx - Lesson and Build Views
src/components/LessonView.tsx - Live Verification
src/components/LiveTestPanel.tsx
Curriculum Pipeline
- Agent Orchestrator
src/lib/agents/orchestrator.ts - Goal Scoping
src/lib/agents/scoper.ts - Curriculum Architecture
src/lib/agents/architect.ts - Reference Implementation
src/lib/agents/implementer.ts - Code Evaluation
src/lib/agents/executor.ts - Learning Step Slicing
src/lib/agents/slicer.ts - Pedagogy Generation
src/lib/agents/pedagogue.ts - Project Catalog
src/lib/catalog/index.ts - Plan Generation
src/app/api/plan/route.ts
Teaching and Evaluation
- Python Execution
src/lib/pyodideRunner.ts - Adaptive Diagnosis
src/lib/diagnostics.ts - Concept Teaching
src/app/api/teach/route.ts - Tutor Questions
src/app/api/ask/route.ts - Teach-Back Evaluation
src/app/api/teachback/route.ts - Model Review
src/app/api/review-model/route.ts - Model Contracts
src/lib/inference.ts - Adversarial Testing
src/lib/redteam.ts - Deployment Roadmap
src/lib/roadmapGenerator.ts - LLM Provider Layer
src/lib/llm.ts
Identity and Persistence
- Authentication API
src/app/api/auth/login/route.ts - Auth Utilities
src/lib/auth.ts - User and Project Records
src/models/User.ts - MongoDB Connection
src/lib/mongodb.ts
Other components
- Learner
- MongoDB Atlas
Connections 38
- Learner → Learning Workspace: opens workspace
- Learning Workspace → Goal Intake: starts goal intake
- Goal Intake → Pipeline Experience: submits goal
- Pipeline Experience → Agent Orchestrator: launches pipeline
src/components/AgentPipelineModal.tsx - Pipeline Experience → Pipeline Progress: shows progress
src/components/AgentPipelineModal.tsx - Agent Orchestrator → Goal Scoping: scopes goal
src/lib/agents/orchestrator.ts - Agent Orchestrator → Curriculum Architecture: builds DAG
src/lib/agents/orchestrator.ts - Agent Orchestrator → Reference Implementation: generates code
src/lib/agents/orchestrator.ts - Agent Orchestrator → Code Evaluation: checks code
src/lib/agents/orchestrator.ts - Agent Orchestrator → Learning Step Slicing: creates steps
src/lib/agents/orchestrator.ts - Agent Orchestrator → Pedagogy Generation: enriches steps
src/lib/agents/orchestrator.ts - Plan Generation → LLM Provider Layer: requests structured plan
src/app/api/plan/route.ts - Plan Generation → Adaptive Diagnosis: builds fallback concepts
src/app/api/plan/route.ts - Plan Generation → Project Catalog: selects project preset
- Agent Orchestrator → Project Catalog: uses project catalog
- Learner → Plan Approval: reviews roadmap
- Plan Approval → Lesson and Build Views: approves plan
- Lesson and Build Views → Adaptive Diagnosis: adapts learning path
- Lesson and Build Views → Concept Teaching: requests instruction
- Concept Teaching → LLM Provider Layer: generates lesson
src/app/api/teach/route.ts - Concept Teaching → Adaptive Diagnosis: uses fallback concepts
src/app/api/teach/route.ts - Lesson and Build Views → Tutor Questions: asks tutor
- Tutor Questions → LLM Provider Layer: generates answer
src/app/api/ask/route.ts - Lesson and Build Views → Teach-Back Evaluation: submits explanation
- Teach-Back Evaluation → LLM Provider Layer: evaluates response
src/app/api/teachback/route.ts - Lesson and Build Views → Python Execution: runs learner code
- Lesson and Build Views → Live Verification: enters live testing
- Live Verification → Adversarial Testing: runs adversarial tests
- Live Verification → Model Review: requests architecture review
- Model Review → Model Contracts: derives model contract
src/app/api/review-model/route.ts - Model Review → Deployment Roadmap: builds fallback review
src/app/api/review-model/route.ts - Model Review → LLM Provider Layer: generates review
src/app/api/review-model/route.ts - Learner → Authentication API: signs in
- Authentication API → Auth Utilities: uses auth utilities
src/app/api/auth/login/route.ts - Authentication API → User and Project Records: reads user record
src/app/api/auth/login/route.ts - Authentication API → MongoDB Connection: connects to database
src/app/api/auth/login/route.ts - MongoDB Connection → MongoDB Atlas: connects to Atlas
- User and Project Records → MongoDB Atlas: stores learner progress