# abdulla6h77/ed-agent architecture

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

- Interactive diagram: https://gitdiagram.com/abdulla6h77/ed-agent
- Repository: https://github.com/abdulla6h77/ed-agent

## Overview

Ed Agent is a Next.js education app for lesson planning, question generation, Socratic tutoring, and a separate homework-grading demo. In the main workflow, a teacher or student uses the web UI to submit a request; an API route optionally looks up curriculum material, calls the AI gateway, and returns a result. The grading slice is a separate TrueForge workflow using rubric retrieval, sandbox checks, and human-approved grade recording. Grading execution links are based on README documentation; the browser grading page is explicitly static.

Main entry points: [`pages/index.js`](https://github.com/abdulla6h77/ed-agent/blob/main/pages/index.js) (Learning interface), [`grading-agent/agent.json`](https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/agent.json) (TrueForge grading agent), [`lib/claude.js`](https://github.com/abdulla6h77/ed-agent/blob/main/lib/claude.js) (Provider selection and JSON parsing), [`pages/api/lesson-plan.js`](https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/lesson-plan.js) (Lesson planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Learning Tools"]
  node_home["Learning interface<br/>[index.js]"]
  node_planner["Lesson planner<br/>[lesson-plan.js]"]
  node_questions["Question generator<br/>[questions.js]"]
  node_tutor["Socratic tutor<br/>[tutor.js]"]
end

subgraph group_grounding["Curriculum Grounding"]
  node_curriculum["Curriculum lookup<br/>[curriculum.js]"]
  node_curriculum_data["Curriculum data<br/>[curriculum.json]"]
end

subgraph group_ai["AI Gateway"]
  node_gateway["Provider selection and JSON parsing<br/>[claude.js]"]
end

subgraph group_grading["Homework Grading"]
  node_grading_page["Grading overview page<br/>[grading-agent.js]"]
  node_grading_agent["TrueForge grading agent<br/>[agent.json]"]
  node_mcp["Rubric MCP server<br/>[mcp-server.mjs]"]
  node_rubrics["Rubric data<br/>[rubrics.json]"]
  node_grade_store[("Finalized grade records<br/>[mcp-server.mjs]")]
end

node_user(("Teacher or student"))
node_anthropic{{"Anthropic API"}}
node_gemini{{"Google Gemini API"}}
node_sandbox{{"Code sandbox"}}
node_approval(("Human approval"))
node_trueforge{{"TrueForge harness"}}

node_user -->|"uses"| node_home
node_home -->|"submits lesson request"| node_planner
node_home -->|"submits question request"| node_questions
node_home -->|"sends messages"| node_tutor
node_planner -->|"looks up topic"| node_curriculum
node_questions -->|"looks up topic"| node_curriculum
node_curriculum -->|"reads"| node_curriculum_data
node_planner -->|"requests lesson plan"| node_gateway
node_questions -->|"requests questions"| node_gateway
node_tutor -->|"requests tutor reply"| node_gateway
node_gateway -->|"calls when configured"| node_anthropic
node_gateway -->|"fallback call"| node_gemini
node_home -->|"links to"| node_grading_page
node_user -.->|"provides answer"| node_grading_agent
node_grading_agent -->|"runs under"| node_trueforge
node_grading_agent -->|"calls rubric tools"| node_mcp
node_grading_agent -->|"checks calculations"| node_sandbox
node_mcp -->|"reads rubric data"| node_rubrics
node_grading_agent -->|"requests grade approval"| node_approval
node_mcp -->|"appends approved grade"| node_grade_store

click node_home "https://github.com/abdulla6h77/ed-agent/blob/main/pages/index.js"
click node_planner "https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/lesson-plan.js"
click node_questions "https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/questions.js"
click node_tutor "https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/tutor.js"
click node_curriculum "https://github.com/abdulla6h77/ed-agent/blob/main/lib/curriculum.js"
click node_curriculum_data "https://github.com/abdulla6h77/ed-agent/blob/main/data/curriculum.json"
click node_gateway "https://github.com/abdulla6h77/ed-agent/blob/main/lib/claude.js"
click node_grading_page "https://github.com/abdulla6h77/ed-agent/blob/main/pages/grading-agent.js"
click node_grading_agent "https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/agent.json"
click node_mcp "https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/mcp-server.mjs"
click node_rubrics "https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/rubrics.json"
click node_grade_store "https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/mcp-server.mjs"

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_home,node_planner,node_questions,node_tutor toneBlue
class node_curriculum,node_curriculum_data toneAmber
class node_gateway,node_anthropic,node_gemini toneMint
class node_grading_page,node_grading_agent,node_mcp,node_rubrics,node_grade_store toneRose
class node_user,node_sandbox,node_approval,node_trueforge toneIndigo
```

## Components

### Learning Tools

- [Learning interface](https://github.com/abdulla6h77/ed-agent/blob/main/pages/index.js): `pages/index.js`
- [Lesson planner](https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/lesson-plan.js): `pages/api/lesson-plan.js`
- [Question generator](https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/questions.js): `pages/api/questions.js`
- [Socratic tutor](https://github.com/abdulla6h77/ed-agent/blob/main/pages/api/tutor.js): `pages/api/tutor.js`

### Curriculum Grounding

- [Curriculum lookup](https://github.com/abdulla6h77/ed-agent/blob/main/lib/curriculum.js): `lib/curriculum.js`
- [Curriculum data](https://github.com/abdulla6h77/ed-agent/blob/main/data/curriculum.json): `data/curriculum.json`

### AI Gateway

- [Provider selection and JSON parsing](https://github.com/abdulla6h77/ed-agent/blob/main/lib/claude.js): `lib/claude.js`

### Homework Grading

- [Grading overview page](https://github.com/abdulla6h77/ed-agent/blob/main/pages/grading-agent.js): `pages/grading-agent.js`
- [TrueForge grading agent](https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/agent.json): `grading-agent/agent.json`
- [Rubric MCP server](https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/mcp-server.mjs): `grading-agent/mcp-server.mjs`
- [Rubric data](https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/rubrics.json): `grading-agent/rubrics.json`
- [Finalized grade records](https://github.com/abdulla6h77/ed-agent/blob/main/grading-agent/mcp-server.mjs): `grading-agent/mcp-server.mjs`

### Other components

- **Teacher or student**
- **Anthropic API**
- **Google Gemini API**
- **Code sandbox**
- **Human approval**
- **TrueForge harness**

## Connections

- Teacher or student → Learning interface: uses (evidence: `README.md`)
- Learning interface → Lesson planner: submits lesson request (evidence: `README.md`)
- Learning interface → Question generator: submits question request (evidence: `README.md`)
- Learning interface → Socratic tutor: sends messages (evidence: `pages/index.js`)
- Lesson planner → Curriculum lookup: looks up topic (evidence: `pages/api/lesson-plan.js`)
- Question generator → Curriculum lookup: looks up topic (evidence: `pages/api/questions.js`)
- Curriculum lookup → Curriculum data: reads (evidence: `lib/curriculum.js`)
- Lesson planner → Provider selection and JSON parsing: requests lesson plan (evidence: `pages/api/lesson-plan.js`)
- Question generator → Provider selection and JSON parsing: requests questions (evidence: `pages/api/questions.js`)
- Socratic tutor → Provider selection and JSON parsing: requests tutor reply (evidence: `pages/api/tutor.js`)
- Provider selection and JSON parsing → Anthropic API: calls when configured (evidence: `lib/claude.js`)
- Provider selection and JSON parsing → Google Gemini API: fallback call (evidence: `lib/claude.js`)
- Learning interface → Grading overview page: links to (evidence: `pages/index.js`)
- Teacher or student → TrueForge grading agent: provides answer (evidence: `README.md`)
- TrueForge grading agent → TrueForge harness: runs under (evidence: `README.md`)
- TrueForge grading agent → Rubric MCP server: calls rubric tools (evidence: `README.md`)
- TrueForge grading agent → Code sandbox: checks calculations (evidence: `README.md`)
- Rubric MCP server → Rubric data: reads rubric data (evidence: `grading-agent/mcp-server.mjs`)
- TrueForge grading agent → Human approval: requests grade approval (evidence: `README.md`)
- Rubric MCP server → Finalized grade records: appends approved grade (evidence: `grading-agent/mcp-server.mjs`)