# darl-genai/instructional_agents architecture

> Architecture diagram of the GitHub repository darl-genai/instructional_agents, 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/darl-genai/instructional_agents
- Repository: https://github.com/darl-genai/instructional_agents

## Overview

Instructional Agents generates and evaluates course materials through an ADDIE-based multi-agent workflow, with web, REST API, and CLI entry points. Users provide course requirements and optionally a catalog or feedback; the system generates instructional content and slides, then compiles or converts the results. A separate optimization workflow analyzes existing PDF slides and creates improved materials. The README also documents catalog and copilot modes, progress monitoring, evaluation, and LaTeX/PPTX outputs. Edges reflect README statements and shown source references; unsampled API routes and internal evaluation wiring are not inferred.

Main entry points: [`src/ADDIE.py`](https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE.py) (ADDIE Workflow), [`src/ADDIE_optimize.py`](https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE_optimize.py) (Optimization Workflow), [`run.py`](https://github.com/darl-genai/instructional_agents/blob/main/run.py) (CLI), [`api_server.py`](https://github.com/darl-genai/instructional_agents/blob/main/api_server.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_web["Web Interface<br/>[app.js]"]
  node_api["REST API<br/>[api_server.py]"]
  node_cli["CLI<br/>[run.py]"]
  node_catalog["Catalog Inputs"]
end

subgraph group_generation["Course Generation"]
  node_addie["ADDIE Workflow<br/>[ADDIE.py]"]
  node_agents["Agent Deliberation<br/>[agents.py]"]
  node_slides["Slide Authoring<br/>[slides.py]"]
  node_llm["OpenAI LLM"]
end

subgraph group_optimization["Slide Optimization"]
  node_optimizer["Optimization Workflow<br/>[ADDIE_optimize.py]"]
  node_pdf["PDF Slide Processing<br/>[pdf_processor.py]"]
  node_knowledge[("Slide Knowledge Base")]
  node_improve["Slide Improvement<br/>[optimize.py]"]
end

subgraph group_outputs["Evaluation and Output"]
  node_evaluation["Course Evaluation<br/>[evaluate.py]"]
  node_evaluation_cli["Evaluation Entry<br/>[evaluate.py]"]
  node_compiler["LaTeX Compilation<br/>[compile.py]"]
  node_pptx["PPTX Conversion<br/>[latex_to_pptx.py]"]
  node_pptx_builder["PPTX Builder<br/>[build_pptx.js]"]
  node_materials["Course Materials"]
end

node_user(("Course Designer"))

node_user -->|"submits requirements"| node_web
node_user -->|"starts generation"| node_cli
node_web -->|"requests tasks"| node_api
node_api -->|"invokes workflow"| node_cli
node_cli -->|"runs generation"| node_addie
node_cli -->|"runs optimization"| node_optimizer
node_catalog -->|"guides generation"| node_addie
node_addie -->|"creates deliberations"| node_agents
node_addie -->|"creates slide decks"| node_slides
node_agents -->|"requests completions"| node_llm
node_optimizer -->|"extracts slide content"| node_pdf
node_optimizer -->|"builds slide index"| node_knowledge
node_optimizer -->|"optimizes chapters"| node_improve
node_improve -->|"searches context"| node_knowledge
node_improve -->|"runs deliberation"| node_agents
node_addie -->|"compiles LaTeX"| node_compiler
node_compiler -->|"offers conversion"| node_pptx
node_api -->|"converts task slides"| node_pptx
node_pptx -->|"builds presentation"| node_pptx_builder
node_addie -.->|"evaluates materials"| node_evaluation
node_evaluation_cli -.->|"uses evaluator"| node_evaluation
node_compiler -.->|"produces PDFs"| node_materials
node_pptx_builder -.->|"produces PPTX"| node_materials
node_evaluation -.->|"assesses materials"| node_materials

click node_web "https://github.com/darl-genai/instructional_agents/blob/main/frontend/app.js"
click node_api "https://github.com/darl-genai/instructional_agents/blob/main/api_server.py"
click node_cli "https://github.com/darl-genai/instructional_agents/blob/main/run.py"
click node_catalog "https://github.com/darl-genai/instructional_agents/tree/main/catalog"
click node_addie "https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE.py"
click node_agents "https://github.com/darl-genai/instructional_agents/blob/main/src/agents.py"
click node_slides "https://github.com/darl-genai/instructional_agents/blob/main/src/slides.py"
click node_optimizer "https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE_optimize.py"
click node_pdf "https://github.com/darl-genai/instructional_agents/blob/main/src/pdf_processor.py"
click node_knowledge "https://github.com/darl-genai/instructional_agents/blob/main/src/slide_knowledge_base.py"
click node_improve "https://github.com/darl-genai/instructional_agents/blob/main/src/optimize.py"
click node_evaluation "https://github.com/darl-genai/instructional_agents/blob/main/src/evaluate.py"
click node_evaluation_cli "https://github.com/darl-genai/instructional_agents/blob/main/evaluate.py"
click node_compiler "https://github.com/darl-genai/instructional_agents/blob/main/src/compile.py"
click node_pptx "https://github.com/darl-genai/instructional_agents/blob/main/src/latex_to_pptx.py"
click node_pptx_builder "https://github.com/darl-genai/instructional_agents/blob/main/src/build_pptx.js"

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_web,node_api,node_cli,node_catalog toneBlue
class node_addie,node_agents,node_slides,node_llm toneAmber
class node_optimizer,node_pdf,node_knowledge,node_improve toneMint
class node_evaluation,node_evaluation_cli,node_compiler,node_pptx,node_pptx_builder,node_materials toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [Web Interface](https://github.com/darl-genai/instructional_agents/blob/main/frontend/app.js): `frontend/app.js`
- [REST API](https://github.com/darl-genai/instructional_agents/blob/main/api_server.py): `api_server.py`
- [CLI](https://github.com/darl-genai/instructional_agents/blob/main/run.py): `run.py`
- [Catalog Inputs](https://github.com/darl-genai/instructional_agents/tree/main/catalog): `catalog`

### Course Generation

- [ADDIE Workflow](https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE.py): `src/ADDIE.py`
- [Agent Deliberation](https://github.com/darl-genai/instructional_agents/blob/main/src/agents.py): `src/agents.py`
- [Slide Authoring](https://github.com/darl-genai/instructional_agents/blob/main/src/slides.py): `src/slides.py`
- **OpenAI LLM**

### Slide Optimization

- [Optimization Workflow](https://github.com/darl-genai/instructional_agents/blob/main/src/ADDIE_optimize.py): `src/ADDIE_optimize.py`
- [PDF Slide Processing](https://github.com/darl-genai/instructional_agents/blob/main/src/pdf_processor.py): `src/pdf_processor.py`
- [Slide Knowledge Base](https://github.com/darl-genai/instructional_agents/blob/main/src/slide_knowledge_base.py): `src/slide_knowledge_base.py`
- [Slide Improvement](https://github.com/darl-genai/instructional_agents/blob/main/src/optimize.py): `src/optimize.py`

### Evaluation and Output

- [Course Evaluation](https://github.com/darl-genai/instructional_agents/blob/main/src/evaluate.py): `src/evaluate.py`
- [Evaluation Entry](https://github.com/darl-genai/instructional_agents/blob/main/evaluate.py): `evaluate.py`
- [LaTeX Compilation](https://github.com/darl-genai/instructional_agents/blob/main/src/compile.py): `src/compile.py`
- [PPTX Conversion](https://github.com/darl-genai/instructional_agents/blob/main/src/latex_to_pptx.py): `src/latex_to_pptx.py`
- [PPTX Builder](https://github.com/darl-genai/instructional_agents/blob/main/src/build_pptx.js): `src/build_pptx.js`
- **Course Materials**

### Other components

- **Course Designer**

## Connections

- Course Designer → Web Interface: submits requirements (evidence: `README.md`)
- Course Designer → CLI: starts generation (evidence: `README.md`)
- Web Interface → REST API: requests tasks (evidence: `README.md`)
- REST API → CLI: invokes workflow (evidence: `api_server.py`)
- CLI → ADDIE Workflow: runs generation (evidence: `run.py`)
- CLI → Optimization Workflow: runs optimization (evidence: `run.py`)
- Catalog Inputs → ADDIE Workflow: guides generation (evidence: `README.md`)
- ADDIE Workflow → Agent Deliberation: creates deliberations (evidence: `src/ADDIE.py`)
- ADDIE Workflow → Slide Authoring: creates slide decks (evidence: `src/ADDIE.py`)
- Agent Deliberation → OpenAI LLM: requests completions (evidence: `src/agents.py`)
- Optimization Workflow → PDF Slide Processing: extracts slide content (evidence: `src/ADDIE_optimize.py`)
- Optimization Workflow → Slide Knowledge Base: builds slide index (evidence: `src/ADDIE_optimize.py`)
- Optimization Workflow → Slide Improvement: optimizes chapters (evidence: `src/ADDIE_optimize.py`)
- Slide Improvement → Slide Knowledge Base: searches context (evidence: `src/optimize.py`)
- Slide Improvement → Agent Deliberation: runs deliberation (evidence: `src/optimize.py`)
- ADDIE Workflow → LaTeX Compilation: compiles LaTeX (evidence: `src/ADDIE.py`)
- LaTeX Compilation → PPTX Conversion: offers conversion (evidence: `src/compile.py`)
- REST API → PPTX Conversion: converts task slides (evidence: `api_server.py`)
- PPTX Conversion → PPTX Builder: builds presentation (evidence: `src/latex_to_pptx.py`)
- ADDIE Workflow → Course Evaluation: evaluates materials
- Evaluation Entry → Course Evaluation: uses evaluator
- LaTeX Compilation → Course Materials: produces PDFs
- PPTX Builder → Course Materials: produces PPTX
- Course Evaluation → Course Materials: assesses materials