# shuchi111/lessonforge architecture

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

- Interactive diagram: https://gitdiagram.com/shuchi111/lessonforge
- Repository: https://github.com/shuchi111/lessonforge

## Overview

LessonForge turns a topic into a beginner lesson, evaluates it against deterministic and model-judged rubric checks, revises failed attempts, and publishes the best result. Its principal workflow is orchestrated by the LangGraph pipeline; persistent memory and reflection create a second, cross-run learning loop. The README documents the main stage connections and capabilities. Some modules are indexed but not excerpted, so edges below rely on those documented relationships rather than claiming their unsampled internals were inspected.

Main entry points: [`src/lessonforge/graph.py`](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/graph.py) (Workflow graph), [`src/lessonforge/memory.py`](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/memory.py) (SQLite run memory), [`src/lessonforge/evaluator/evaluate.py`](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/evaluate.py) (Evaluation coordinator), [`src/lessonforge/evaluator/deterministic.py`](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/deterministic.py) (Code checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Command interface<br/>[cli.py]"]
  node_visualizer["Run visualizer<br/>[app.py]"]
end

subgraph group_workflow["Lesson workflow"]
  node_factory["Dependency factory<br/>[factory.py]"]
  node_pipeline["Workflow graph<br/>[graph.py]"]
  node_prompting["Plan and revise<br/>[prompts.py]"]
  node_format["Lesson structure<br/>[lesson_format.py]"]
  node_injection["Error injection<br/>[inject.py]"]
  node_render["Run artifacts<br/>[render.py]"]
  node_llm["Groq model access<br/>[llm.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_quality["Quality evaluation"]
  node_evaluation["Evaluation coordinator<br/>[evaluate.py]"]
  node_deterministic["Code checks<br/>[deterministic.py]"]
  node_text["Text analysis<br/>[text.py]"]
  node_judges["LLM judges<br/>[judges.py]"]
  node_schemas["Run and verdict schemas<br/>[schemas.py]"]
end

subgraph group_knowledge["Knowledge and prompts"]
  node_knowledge_loader["Topic and rules loader<br/>[knowledge.py]"]
  node_topic_pack["Topic facts<br/>[topic.yaml]"]
  node_fact_sheet["Fact sheet<br/>[fact_sheet.md]"]
  node_rubric["Quality rubric<br/>[rubric.yaml]"]
  node_jargon["Jargon rules<br/>[jargon.yaml]"]
end

subgraph group_learning["Memory and learning"]
  node_memory[("SQLite run memory<br/>[memory.py]")]
  node_reflection["Cross-run reflection<br/>[reflection.py]"]
end

node_user(("Topic author"))
node_human(("Human reviewer"))

node_user -->|"starts run"| node_cli
node_cli -->|"builds dependencies"| node_factory
node_factory -->|"creates workflow"| node_pipeline
node_pipeline -->|"loads topic pack"| node_knowledge_loader
node_knowledge_loader -->|"reads topic data"| node_topic_pack
node_knowledge_loader -->|"reads facts"| node_fact_sheet
node_pipeline -->|"loads learned rules"| node_memory
node_pipeline -->|"plans and revises"| node_prompting
node_prompting -->|"requests writing"| node_llm
node_prompting -->|"uses structure"| node_format
node_pipeline -.->|"injects errors"| node_injection
node_pipeline -->|"evaluates attempts"| node_evaluation
node_evaluation -->|"runs code checks"| node_deterministic
node_evaluation -->|"runs model checks"| node_judges
node_deterministic -->|"analyzes text"| node_text
node_deterministic -->|"applies checks"| node_rubric
node_deterministic -->|"checks jargon"| node_jargon
node_judges -->|"requests verdicts"| node_llm
node_judges -->|"grounds accuracy"| node_fact_sheet
node_pipeline -->|"writes outputs"| node_render
node_pipeline -->|"persists run"| node_memory
node_pipeline -->|"triggers learning"| node_reflection
node_reflection -->|"reads failures"| node_memory
node_reflection -->|"proposes rules"| node_llm
node_reflection -->|"informs future writing"| node_prompting
node_cli -->|"manages feedback"| node_memory
node_human -->|"submits feedback"| node_cli
node_pipeline -->|"flags failed result"| node_human
node_user -->|"opens walkthrough"| node_visualizer
node_visualizer -->|"shows run history"| node_memory
node_factory -->|"loads settings"| node_config
node_evaluation -->|"returns evaluations"| node_schemas

click node_cli "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/cli.py"
click node_visualizer "https://github.com/shuchi111/lessonforge/blob/main/app.py"
click node_factory "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/factory.py"
click node_pipeline "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/graph.py"
click node_prompting "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/prompts.py"
click node_format "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/lesson_format.py"
click node_injection "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/inject.py"
click node_render "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/render.py"
click node_llm "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/llm.py"
click node_evaluation "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/evaluate.py"
click node_deterministic "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/deterministic.py"
click node_text "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/text.py"
click node_judges "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/judges.py"
click node_schemas "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/schemas.py"
click node_knowledge_loader "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/knowledge.py"
click node_topic_pack "https://github.com/shuchi111/lessonforge/blob/main/data/topics/rag/topic.yaml"
click node_fact_sheet "https://github.com/shuchi111/lessonforge/blob/main/data/topics/rag/fact_sheet.md"
click node_rubric "https://github.com/shuchi111/lessonforge/blob/main/data/rubric.yaml"
click node_jargon "https://github.com/shuchi111/lessonforge/blob/main/data/jargon.yaml"
click node_memory "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/memory.py"
click node_reflection "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/reflection.py"
click node_config "https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/config.py"

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_cli,node_visualizer,node_human toneBlue
class node_factory,node_pipeline,node_prompting,node_format,node_injection,node_render,node_llm,node_config toneAmber
class node_evaluation,node_deterministic,node_text,node_judges,node_schemas toneMint
class node_knowledge_loader,node_topic_pack,node_fact_sheet,node_rubric,node_jargon toneRose
class node_memory,node_reflection,node_user toneIndigo
```

## Components

### User entry points

- [Command interface](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/cli.py): `src/lessonforge/cli.py`
- [Run visualizer](https://github.com/shuchi111/lessonforge/blob/main/app.py): `app.py`

### Lesson workflow

- [Dependency factory](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/factory.py): `src/lessonforge/factory.py`
- [Workflow graph](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/graph.py): `src/lessonforge/graph.py`
- [Plan and revise](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/prompts.py): `src/lessonforge/prompts.py`
- [Lesson structure](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/lesson_format.py): `src/lessonforge/lesson_format.py`
- [Error injection](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/inject.py): `src/lessonforge/inject.py`
- [Run artifacts](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/render.py): `src/lessonforge/render.py`
- [Groq model access](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/llm.py): `src/lessonforge/llm.py`
- [Runtime settings](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/config.py): `src/lessonforge/config.py`

### Quality evaluation

- [Evaluation coordinator](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/evaluate.py): `src/lessonforge/evaluator/evaluate.py`
- [Code checks](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/deterministic.py): `src/lessonforge/evaluator/deterministic.py`
- [Text analysis](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/text.py): `src/lessonforge/evaluator/text.py`
- [LLM judges](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/evaluator/judges.py): `src/lessonforge/evaluator/judges.py`
- [Run and verdict schemas](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/schemas.py): `src/lessonforge/schemas.py`

### Knowledge and prompts

- [Topic and rules loader](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/knowledge.py): `src/lessonforge/knowledge.py`
- [Topic facts](https://github.com/shuchi111/lessonforge/blob/main/data/topics/rag/topic.yaml): `data/topics/rag/topic.yaml`
- [Fact sheet](https://github.com/shuchi111/lessonforge/blob/main/data/topics/rag/fact_sheet.md): `data/topics/rag/fact_sheet.md`
- [Quality rubric](https://github.com/shuchi111/lessonforge/blob/main/data/rubric.yaml): `data/rubric.yaml`
- [Jargon rules](https://github.com/shuchi111/lessonforge/blob/main/data/jargon.yaml): `data/jargon.yaml`

### Memory and learning

- [SQLite run memory](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/memory.py): `src/lessonforge/memory.py`
- [Cross-run reflection](https://github.com/shuchi111/lessonforge/blob/main/src/lessonforge/reflection.py): `src/lessonforge/reflection.py`

### Other components

- **Topic author**
- **Human reviewer**

## Connections

- Topic author → Command interface: starts run (evidence: `README.md`)
- Command interface → Dependency factory: builds dependencies (evidence: `README.md`)
- Dependency factory → Workflow graph: creates workflow (evidence: `README.md`)
- Workflow graph → Topic and rules loader: loads topic pack (evidence: `README.md`)
- Topic and rules loader → Topic facts: reads topic data (evidence: `README.md`)
- Topic and rules loader → Fact sheet: reads facts (evidence: `README.md`)
- Workflow graph → SQLite run memory: loads learned rules (evidence: `README.md`)
- Workflow graph → Plan and revise: plans and revises (evidence: `README.md`)
- Plan and revise → Groq model access: requests writing (evidence: `README.md`)
- Plan and revise → Lesson structure: uses structure (evidence: `README.md`)
- Workflow graph → Error injection: injects errors (evidence: `README.md`)
- Workflow graph → Evaluation coordinator: evaluates attempts (evidence: `README.md`)
- Evaluation coordinator → Code checks: runs code checks (evidence: `README.md`)
- Evaluation coordinator → LLM judges: runs model checks (evidence: `README.md`)
- Code checks → Text analysis: analyzes text (evidence: `src/lessonforge/evaluator/deterministic.py`)
- Code checks → Quality rubric: applies checks (evidence: `README.md`)
- Code checks → Jargon rules: checks jargon (evidence: `README.md`)
- LLM judges → Groq model access: requests verdicts (evidence: `README.md`)
- LLM judges → Fact sheet: grounds accuracy (evidence: `README.md`)
- Workflow graph → Run artifacts: writes outputs (evidence: `README.md`)
- Workflow graph → SQLite run memory: persists run (evidence: `README.md`)
- Workflow graph → Cross-run reflection: triggers learning (evidence: `README.md`)
- Cross-run reflection → SQLite run memory: reads failures (evidence: `src/lessonforge/reflection.py`)
- Cross-run reflection → Groq model access: proposes rules (evidence: `src/lessonforge/reflection.py`)
- Cross-run reflection → Plan and revise: informs future writing (evidence: `README.md`)
- Command interface → SQLite run memory: manages feedback (evidence: `README.md`)
- Human reviewer → Command interface: submits feedback (evidence: `README.md`)
- Workflow graph → Human reviewer: flags failed result (evidence: `README.md`)
- Topic author → Run visualizer: opens walkthrough (evidence: `README.md`)
- Run visualizer → SQLite run memory: shows run history (evidence: `app.py`)
- Dependency factory → Runtime settings: loads settings (evidence: `README.md`)
- Evaluation coordinator → Run and verdict schemas: returns evaluations (evidence: `src/lessonforge/evaluator/evaluate.py`)
