# suhas1010/socrates architecture

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

- Interactive diagram: https://gitdiagram.com/suhas1010/socrates
- Repository: https://github.com/suhas1010/socrates

## Overview

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: [`src/lib/agents/orchestrator.ts`](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/orchestrator.ts) (Agent Orchestrator), [`src/components/LessonView.tsx`](https://github.com/suhas1010/socrates/blob/main/src/components/LessonView.tsx) (Lesson and Build Views), [`src/lib/llm.ts`](https://github.com/suhas1010/socrates/blob/main/src/lib/llm.ts) (LLM Provider Layer), [`src/app/api/review-model/route.ts`](https://github.com/suhas1010/socrates/blob/main/src/app/api/review-model/route.ts) (Model Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner["Learner Experience"]
  node_workspace["Learning Workspace<br/>[page.tsx]"]
  node_goalintake["Goal Intake<br/>[LandingView.tsx]"]
  node_pipelineui["Pipeline Experience"]
  node_loading["Pipeline Progress"]
  node_planreview["Plan Approval<br/>[PlanReviewView.tsx]"]
  node_learningviews["Lesson and Build Views<br/>[LessonView.tsx]"]
  node_liveverify["Live Verification<br/>[LiveTestPanel.tsx]"]
end

subgraph group_curriculum["Curriculum Pipeline"]
  node_agentorchestrator["Agent Orchestrator<br/>[orchestrator.ts]"]
  node_scoper["Goal Scoping<br/>[scoper.ts]"]
  node_architect["Curriculum Architecture<br/>[architect.ts]"]
  node_implementer["Reference Implementation<br/>[implementer.ts]"]
  node_executor["Code Evaluation<br/>[executor.ts]"]
  node_slicer["Learning Step Slicing<br/>[slicer.ts]"]
  node_pedagogue["Pedagogy Generation<br/>[pedagogue.ts]"]
  node_catalog["Project Catalog<br/>[index.ts]"]
  node_planapi["Plan Generation<br/>[route.ts]"]
end

subgraph group_learning["Teaching and Evaluation"]
  node_pythonruntime["Python Execution<br/>[pyodideRunner.ts]"]
  node_diagnostics["Adaptive Diagnosis<br/>[diagnostics.ts]"]
  node_teachapi["Concept Teaching<br/>[route.ts]"]
  node_askapi["Tutor Questions<br/>[route.ts]"]
  node_teachback["Teach-Back Evaluation<br/>[route.ts]"]
  node_review["Model Review<br/>[route.ts]"]
  node_inference["Model Contracts<br/>[inference.ts]"]
  node_redteam["Adversarial Testing<br/>[redteam.ts]"]
  node_roadmap["Deployment Roadmap"]
  node_llm["LLM Provider Layer<br/>[llm.ts]"]
end

subgraph group_platform["Identity and Persistence"]
  node_login["Authentication API<br/>[route.ts]"]
  node_authlib["Auth Utilities<br/>[auth.ts]"]
  node_usermodel["User and Project Records<br/>[User.ts]"]
  node_mongodb[("MongoDB Connection<br/>[mongodb.ts]")]
end

node_learner(("Learner"))
node_cloudmongo[("MongoDB Atlas")]

node_learner -->|"opens workspace"| node_workspace
node_workspace -->|"starts goal intake"| node_goalintake
node_goalintake -->|"submits goal"| node_pipelineui
node_pipelineui -->|"launches pipeline"| node_agentorchestrator
node_pipelineui -->|"shows progress"| node_loading
node_agentorchestrator -->|"scopes goal"| node_scoper
node_agentorchestrator -->|"builds DAG"| node_architect
node_agentorchestrator -->|"generates code"| node_implementer
node_agentorchestrator -->|"checks code"| node_executor
node_agentorchestrator -->|"creates steps"| node_slicer
node_agentorchestrator -->|"enriches steps"| node_pedagogue
node_planapi -->|"requests structured plan"| node_llm
node_planapi -->|"builds fallback concepts"| node_diagnostics
node_planapi -.->|"selects project preset"| node_catalog
node_agentorchestrator -.->|"uses project catalog"| node_catalog
node_learner -->|"reviews roadmap"| node_planreview
node_planreview -->|"approves plan"| node_learningviews
node_learningviews -->|"adapts learning path"| node_diagnostics
node_learningviews -->|"requests instruction"| node_teachapi
node_teachapi -->|"generates lesson"| node_llm
node_teachapi -->|"uses fallback concepts"| node_diagnostics
node_learningviews -->|"asks tutor"| node_askapi
node_askapi -->|"generates answer"| node_llm
node_learningviews -->|"submits explanation"| node_teachback
node_teachback -->|"evaluates response"| node_llm
node_learningviews -->|"runs learner code"| node_pythonruntime
node_learningviews -->|"enters live testing"| node_liveverify
node_liveverify -->|"runs adversarial tests"| node_redteam
node_liveverify -->|"requests architecture review"| node_review
node_review -->|"derives model contract"| node_inference
node_review -->|"builds fallback review"| node_roadmap
node_review -->|"generates review"| node_llm
node_learner -->|"signs in"| node_login
node_login -->|"uses auth utilities"| node_authlib
node_login -->|"reads user record"| node_usermodel
node_login -->|"connects to database"| node_mongodb
node_mongodb -->|"connects to Atlas"| node_cloudmongo
node_usermodel -->|"stores learner progress"| node_cloudmongo

click node_workspace "https://github.com/suhas1010/socrates/blob/main/src/app/page.tsx"
click node_goalintake "https://github.com/suhas1010/socrates/blob/main/src/components/LandingView.tsx"
click node_pipelineui "https://github.com/suhas1010/socrates/blob/main/src/components/AgentPipelineModal.tsx"
click node_loading "https://github.com/suhas1010/socrates/blob/main/src/components/LearnerPipelineLoading.tsx"
click node_planreview "https://github.com/suhas1010/socrates/blob/main/src/components/PlanReviewView.tsx"
click node_learningviews "https://github.com/suhas1010/socrates/blob/main/src/components/LessonView.tsx"
click node_liveverify "https://github.com/suhas1010/socrates/blob/main/src/components/LiveTestPanel.tsx"
click node_pythonruntime "https://github.com/suhas1010/socrates/blob/main/src/lib/pyodideRunner.ts"
click node_agentorchestrator "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/orchestrator.ts"
click node_scoper "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/scoper.ts"
click node_architect "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/architect.ts"
click node_implementer "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/implementer.ts"
click node_executor "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/executor.ts"
click node_slicer "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/slicer.ts"
click node_pedagogue "https://github.com/suhas1010/socrates/blob/main/src/lib/agents/pedagogue.ts"
click node_catalog "https://github.com/suhas1010/socrates/blob/main/src/lib/catalog/index.ts"
click node_planapi "https://github.com/suhas1010/socrates/blob/main/src/app/api/plan/route.ts"
click node_diagnostics "https://github.com/suhas1010/socrates/blob/main/src/lib/diagnostics.ts"
click node_teachapi "https://github.com/suhas1010/socrates/blob/main/src/app/api/teach/route.ts"
click node_askapi "https://github.com/suhas1010/socrates/blob/main/src/app/api/ask/route.ts"
click node_teachback "https://github.com/suhas1010/socrates/blob/main/src/app/api/teachback/route.ts"
click node_review "https://github.com/suhas1010/socrates/blob/main/src/app/api/review-model/route.ts"
click node_inference "https://github.com/suhas1010/socrates/blob/main/src/lib/inference.ts"
click node_redteam "https://github.com/suhas1010/socrates/blob/main/src/lib/redteam.ts"
click node_roadmap "https://github.com/suhas1010/socrates/blob/main/src/lib/roadmapGenerator.ts"
click node_llm "https://github.com/suhas1010/socrates/blob/main/src/lib/llm.ts"
click node_login "https://github.com/suhas1010/socrates/blob/main/src/app/api/auth/login/route.ts"
click node_authlib "https://github.com/suhas1010/socrates/blob/main/src/lib/auth.ts"
click node_usermodel "https://github.com/suhas1010/socrates/blob/main/src/models/User.ts"
click node_mongodb "https://github.com/suhas1010/socrates/blob/main/src/lib/mongodb.ts"

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_goalintake,node_pipelineui,node_loading,node_planreview,node_learningviews,node_liveverify toneBlue
class node_agentorchestrator,node_scoper,node_architect,node_implementer,node_executor,node_slicer,node_pedagogue,node_catalog,node_planapi,node_cloudmongo toneAmber
class node_pythonruntime,node_diagnostics,node_teachapi,node_askapi,node_teachback,node_review,node_inference,node_redteam,node_roadmap,node_llm toneMint
class node_login,node_authlib,node_usermodel,node_mongodb toneRose
class node_learner toneIndigo
```

## Components

### Learner Experience

- [Learning Workspace](https://github.com/suhas1010/socrates/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Goal Intake](https://github.com/suhas1010/socrates/blob/main/src/components/LandingView.tsx): `src/components/LandingView.tsx`
- [Pipeline Experience](https://github.com/suhas1010/socrates/blob/main/src/components/AgentPipelineModal.tsx): `src/components/AgentPipelineModal.tsx`
- [Pipeline Progress](https://github.com/suhas1010/socrates/blob/main/src/components/LearnerPipelineLoading.tsx): `src/components/LearnerPipelineLoading.tsx`
- [Plan Approval](https://github.com/suhas1010/socrates/blob/main/src/components/PlanReviewView.tsx): `src/components/PlanReviewView.tsx`
- [Lesson and Build Views](https://github.com/suhas1010/socrates/blob/main/src/components/LessonView.tsx): `src/components/LessonView.tsx`
- [Live Verification](https://github.com/suhas1010/socrates/blob/main/src/components/LiveTestPanel.tsx): `src/components/LiveTestPanel.tsx`

### Curriculum Pipeline

- [Agent Orchestrator](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/orchestrator.ts): `src/lib/agents/orchestrator.ts`
- [Goal Scoping](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/scoper.ts): `src/lib/agents/scoper.ts`
- [Curriculum Architecture](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/architect.ts): `src/lib/agents/architect.ts`
- [Reference Implementation](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/implementer.ts): `src/lib/agents/implementer.ts`
- [Code Evaluation](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/executor.ts): `src/lib/agents/executor.ts`
- [Learning Step Slicing](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/slicer.ts): `src/lib/agents/slicer.ts`
- [Pedagogy Generation](https://github.com/suhas1010/socrates/blob/main/src/lib/agents/pedagogue.ts): `src/lib/agents/pedagogue.ts`
- [Project Catalog](https://github.com/suhas1010/socrates/blob/main/src/lib/catalog/index.ts): `src/lib/catalog/index.ts`
- [Plan Generation](https://github.com/suhas1010/socrates/blob/main/src/app/api/plan/route.ts): `src/app/api/plan/route.ts`

### Teaching and Evaluation

- [Python Execution](https://github.com/suhas1010/socrates/blob/main/src/lib/pyodideRunner.ts): `src/lib/pyodideRunner.ts`
- [Adaptive Diagnosis](https://github.com/suhas1010/socrates/blob/main/src/lib/diagnostics.ts): `src/lib/diagnostics.ts`
- [Concept Teaching](https://github.com/suhas1010/socrates/blob/main/src/app/api/teach/route.ts): `src/app/api/teach/route.ts`
- [Tutor Questions](https://github.com/suhas1010/socrates/blob/main/src/app/api/ask/route.ts): `src/app/api/ask/route.ts`
- [Teach-Back Evaluation](https://github.com/suhas1010/socrates/blob/main/src/app/api/teachback/route.ts): `src/app/api/teachback/route.ts`
- [Model Review](https://github.com/suhas1010/socrates/blob/main/src/app/api/review-model/route.ts): `src/app/api/review-model/route.ts`
- [Model Contracts](https://github.com/suhas1010/socrates/blob/main/src/lib/inference.ts): `src/lib/inference.ts`
- [Adversarial Testing](https://github.com/suhas1010/socrates/blob/main/src/lib/redteam.ts): `src/lib/redteam.ts`
- [Deployment Roadmap](https://github.com/suhas1010/socrates/blob/main/src/lib/roadmapGenerator.ts): `src/lib/roadmapGenerator.ts`
- [LLM Provider Layer](https://github.com/suhas1010/socrates/blob/main/src/lib/llm.ts): `src/lib/llm.ts`

### Identity and Persistence

- [Authentication API](https://github.com/suhas1010/socrates/blob/main/src/app/api/auth/login/route.ts): `src/app/api/auth/login/route.ts`
- [Auth Utilities](https://github.com/suhas1010/socrates/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [User and Project Records](https://github.com/suhas1010/socrates/blob/main/src/models/User.ts): `src/models/User.ts`
- [MongoDB Connection](https://github.com/suhas1010/socrates/blob/main/src/lib/mongodb.ts): `src/lib/mongodb.ts`

### Other components

- **Learner**
- **MongoDB Atlas**

## Connections

- Learner → Learning Workspace: opens workspace
- Learning Workspace → Goal Intake: starts goal intake
- Goal Intake → Pipeline Experience: submits goal
- Pipeline Experience → Agent Orchestrator: launches pipeline (evidence: `src/components/AgentPipelineModal.tsx`)
- Pipeline Experience → Pipeline Progress: shows progress (evidence: `src/components/AgentPipelineModal.tsx`)
- Agent Orchestrator → Goal Scoping: scopes goal (evidence: `src/lib/agents/orchestrator.ts`)
- Agent Orchestrator → Curriculum Architecture: builds DAG (evidence: `src/lib/agents/orchestrator.ts`)
- Agent Orchestrator → Reference Implementation: generates code (evidence: `src/lib/agents/orchestrator.ts`)
- Agent Orchestrator → Code Evaluation: checks code (evidence: `src/lib/agents/orchestrator.ts`)
- Agent Orchestrator → Learning Step Slicing: creates steps (evidence: `src/lib/agents/orchestrator.ts`)
- Agent Orchestrator → Pedagogy Generation: enriches steps (evidence: `src/lib/agents/orchestrator.ts`)
- Plan Generation → LLM Provider Layer: requests structured plan (evidence: `src/app/api/plan/route.ts`)
- Plan Generation → Adaptive Diagnosis: builds fallback concepts (evidence: `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 (evidence: `src/app/api/teach/route.ts`)
- Concept Teaching → Adaptive Diagnosis: uses fallback concepts (evidence: `src/app/api/teach/route.ts`)
- Lesson and Build Views → Tutor Questions: asks tutor
- Tutor Questions → LLM Provider Layer: generates answer (evidence: `src/app/api/ask/route.ts`)
- Lesson and Build Views → Teach-Back Evaluation: submits explanation
- Teach-Back Evaluation → LLM Provider Layer: evaluates response (evidence: `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 (evidence: `src/app/api/review-model/route.ts`)
- Model Review → Deployment Roadmap: builds fallback review (evidence: `src/app/api/review-model/route.ts`)
- Model Review → LLM Provider Layer: generates review (evidence: `src/app/api/review-model/route.ts`)
- Learner → Authentication API: signs in
- Authentication API → Auth Utilities: uses auth utilities (evidence: `src/app/api/auth/login/route.ts`)
- Authentication API → User and Project Records: reads user record (evidence: `src/app/api/auth/login/route.ts`)
- Authentication API → MongoDB Connection: connects to database (evidence: `src/app/api/auth/login/route.ts`)
- MongoDB Connection → MongoDB Atlas: connects to Atlas
- User and Project Records → MongoDB Atlas: stores learner progress
