# starstarn/lessonpreparation architecture

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

- Interactive diagram: https://gitdiagram.com/starstarn/lessonpreparation
- Repository: https://github.com/starstarn/lessonpreparation

## Overview

This is a K–12 teacher lesson-preparation workbench. A teacher selects or customizes a lesson in the React interface, starts a run through the FastAPI API, and follows the job as the workflow interprets curriculum, drafts and reviews a lesson plan, pauses for teacher confirmation, then generates exercises, slides, and a blackboard design in parallel. A consistency check can send conflicting materials back for revision. Results can be edited, versioned, and exported. The README documents these capabilities; some backend routes and agent wiring were not sampled, so uncertain links are omitted.

Main entry points: [`src/lesson_prep/graph.py`](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/graph.py) (Workflow graph), [`web/src/api.ts`](https://github.com/starstarn/lessonpreparation/blob/main/web/src/api.ts) (API client), [`web/src/App.tsx`](https://github.com/starstarn/lessonpreparation/blob/main/web/src/App.tsx) (Workbench app), [`src/lesson_prep/agents.py`](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py) (Parallel materials)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Teacher workbench"]
  node_form["Lesson form<br/>[LessonForm.tsx]"]
  node_progress["Run progress<br/>[AgentProgress.tsx]"]
  node_result_panel["Results panel<br/>[ResultPanel.tsx]"]
  node_app["Workbench app<br/>[App.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_runtime["Run orchestration"]
  node_api["FastAPI service<br/>[api.py]"]
  node_jobs["Run jobs<br/>[jobs.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
end

subgraph group_content["Preparation agents"]
  node_agents["Agent implementations<br/>[agents.py]"]
  node_curriculum["Curriculum interpretation<br/>[agents.py]"]
  node_plan_review["Plan and review<br/>[agents.py]"]
  node_parallel_materials["Parallel materials<br/>[agents.py]"]
  node_consistency["Consistency check<br/>[agents.py]"]
end

subgraph group_knowledge["Knowledge and media"]
  node_rag["Curriculum retrieval<br/>[rag.py]"]
  node_question_bank["Question bank<br/>[question_bank.py]"]
  node_media["Image and diagrams<br/>[media_assets.py]"]
  node_catalog["Lesson catalog<br/>[catalog.py]"]
  node_llm["Model clients<br/>[llm.py]"]
  node_files["Curriculum and bank data"]
end

subgraph group_results["Results and export"]
  node_versioning["Saved versions<br/>[versions.py]"]
  node_export["Document export<br/>[export_docs.py]"]
end

node_teacher(("Teacher"))
node_model_service{{"LLM provider"}}

node_teacher -->|"enters lesson"| node_form
node_form -->|"submits input"| node_app
node_app -->|"requests runs"| node_web_api
node_app -->|"shows status"| node_progress
node_app -->|"shows results"| node_result_panel
node_web_api -->|"calls endpoints"| node_api
node_api -->|"serves catalog"| node_catalog
node_api -->|"starts or updates"| node_jobs
node_jobs -->|"runs workflow"| node_graph
node_graph -->|"dispatches stages"| node_agents
node_graph -->|"runs interpretation"| node_curriculum
node_curriculum -->|"searches curriculum"| node_rag
node_graph -->|"drafts and reviews"| node_plan_review
node_plan_review -->|"requests generation"| node_llm
node_graph -->|"starts parallel work"| node_parallel_materials
node_parallel_materials -->|"searches questions"| node_question_bank
node_parallel_materials -->|"gets visuals"| node_media
node_parallel_materials -->|"requests generation"| node_llm
node_graph -->|"checks alignment"| node_consistency
node_consistency -->|"returns revisions"| node_graph
node_rag -->|"reads curriculum"| node_files
node_question_bank -->|"reads question data"| node_files
node_llm -.->|"invokes model"| node_model_service
node_result_panel -->|"saves or exports"| node_web_api
node_web_api -->|"manages versions"| node_versioning
node_web_api -->|"requests documents"| node_export

click node_form "https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/LessonForm.tsx"
click node_progress "https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/AgentProgress.tsx"
click node_result_panel "https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/ResultPanel.tsx"
click node_app "https://github.com/starstarn/lessonpreparation/blob/main/web/src/App.tsx"
click node_web_api "https://github.com/starstarn/lessonpreparation/blob/main/web/src/api.ts"
click node_api "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/api.py"
click node_jobs "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/jobs.py"
click node_graph "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/graph.py"
click node_agents "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py"
click node_curriculum "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py"
click node_plan_review "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py"
click node_parallel_materials "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py"
click node_consistency "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py"
click node_rag "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/rag.py"
click node_question_bank "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/question_bank.py"
click node_media "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/media_assets.py"
click node_catalog "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/catalog.py"
click node_llm "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/llm.py"
click node_versioning "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/versions.py"
click node_export "https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/export_docs.py"
click node_files "https://github.com/starstarn/lessonpreparation/tree/main/doc"

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_form,node_progress,node_result_panel,node_app,node_web_api toneBlue
class node_api,node_jobs,node_graph toneAmber
class node_agents,node_curriculum,node_plan_review,node_parallel_materials,node_consistency toneMint
class node_rag,node_question_bank,node_media,node_catalog,node_llm,node_files toneRose
class node_versioning,node_export,node_teacher,node_model_service toneIndigo
```

## Components

### Teacher workbench

- [Lesson form](https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/LessonForm.tsx): `web/src/components/LessonForm.tsx`
- [Run progress](https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/AgentProgress.tsx): `web/src/components/AgentProgress.tsx`
- [Results panel](https://github.com/starstarn/lessonpreparation/blob/main/web/src/components/ResultPanel.tsx): `web/src/components/ResultPanel.tsx`
- [Workbench app](https://github.com/starstarn/lessonpreparation/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [API client](https://github.com/starstarn/lessonpreparation/blob/main/web/src/api.ts): `web/src/api.ts`

### Run orchestration

- [FastAPI service](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/api.py): `src/lesson_prep/api.py`
- [Run jobs](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/jobs.py): `src/lesson_prep/jobs.py`
- [Workflow graph](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/graph.py): `src/lesson_prep/graph.py`

### Preparation agents

- [Agent implementations](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py): `src/lesson_prep/agents.py`
- [Curriculum interpretation](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py): `src/lesson_prep/agents.py`
- [Plan and review](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py): `src/lesson_prep/agents.py`
- [Parallel materials](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py): `src/lesson_prep/agents.py`
- [Consistency check](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/agents.py): `src/lesson_prep/agents.py`

### Knowledge and media

- [Curriculum retrieval](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/rag.py): `src/lesson_prep/rag.py`
- [Question bank](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/question_bank.py): `src/lesson_prep/question_bank.py`
- [Image and diagrams](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/media_assets.py): `src/lesson_prep/media_assets.py`
- [Lesson catalog](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/catalog.py): `src/lesson_prep/catalog.py`
- [Model clients](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/llm.py): `src/lesson_prep/llm.py`
- [Curriculum and bank data](https://github.com/starstarn/lessonpreparation/tree/main/doc): `doc`

### Results and export

- [Saved versions](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/versions.py): `src/lesson_prep/versions.py`
- [Document export](https://github.com/starstarn/lessonpreparation/blob/main/src/lesson_prep/export_docs.py): `src/lesson_prep/export_docs.py`

### Other components

- **Teacher**
- **LLM provider**

## Connections

- Teacher → Lesson form: enters lesson
- Lesson form → Workbench app: submits input
- Workbench app → API client: requests runs
- Workbench app → Run progress: shows status
- Workbench app → Results panel: shows results
- API client → FastAPI service: calls endpoints
- FastAPI service → Lesson catalog: serves catalog
- FastAPI service → Run jobs: starts or updates
- Run jobs → Workflow graph: runs workflow
- Workflow graph → Agent implementations: dispatches stages
- Workflow graph → Curriculum interpretation: runs interpretation
- Curriculum interpretation → Curriculum retrieval: searches curriculum
- Workflow graph → Plan and review: drafts and reviews
- Plan and review → Model clients: requests generation
- Workflow graph → Parallel materials: starts parallel work
- Parallel materials → Question bank: searches questions
- Parallel materials → Image and diagrams: gets visuals
- Parallel materials → Model clients: requests generation
- Workflow graph → Consistency check: checks alignment
- Consistency check → Workflow graph: returns revisions
- Curriculum retrieval → Curriculum and bank data: reads curriculum
- Question bank → Curriculum and bank data: reads question data
- Model clients → LLM provider: invokes model
- Results panel → API client: saves or exports
- API client → Saved versions: manages versions
- API client → Document export: requests documents