# thu-maic/openmaic architecture

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

- Interactive diagram: https://gitdiagram.com/thu-maic/openmaic
- Repository: https://github.com/thu-maic/openmaic
- Video tour (about a minute): https://gitdiagram.com/thu-maic/openmaic/video

## Overview

OpenMAIC turns a learner’s topic or documents into an interactive, multi-agent classroom, then supports learning, editing, and export. The primary path is request → durable server-side generation run → persisted classroom → classroom playback; the README also describes previews, knowledge-base materials, agentic chat, PBL, and export. Paths for major capabilities come from the tree; edges rely on README statements or SOURCE INDEX references, so unsampled implementation details and wiring are omitted.

Main entry points: [`lib/server/generation/run/engine.ts`](https://github.com/thu-maic/openmaic/blob/main/lib/server/generation/run/engine.ts) (Durable generation run), [`app/classroom/[id]/page.tsx`](https://github.com/thu-maic/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx) (Classroom playback), [`app/api/generate-classroom/route.ts`](https://github.com/thu-maic/openmaic/blob/main/app/api/generate-classroom/route.ts) (Generation API), [`lib/document-store/index.ts`](https://github.com/thu-maic/openmaic/blob/main/lib/document-store/index.ts) (Document store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_workbench["Workbench request<br/>[client.tsx]"]
  node_preview["Generation preview<br/>[page.tsx]"]
end

subgraph group_generation["Generation"]
  node_generation_api["Generation API<br/>[route.ts]"]
  node_run_engine["Durable generation run<br/>[engine.ts]"]
  node_run_status["Run status and events<br/>[route.ts]"]
end

subgraph group_classroom["Classroom runtime"]
  node_classroom["Classroom playback<br/>[page.tsx]"]
  node_playback["Playback engine<br/>[engine.ts]"]
  node_action_engine["Action execution<br/>[engine.ts]"]
  node_editor["Classroom editor<br/>[EditShell.tsx]"]
  node_pbl["PBL experience<br/>[pbl-renderer.tsx]"]
  node_export["Classroom export<br/>[index.ts]"]
end

subgraph group_knowledge["Knowledge and agents"]
  node_materials["Material library<br/>[route.ts]"]
  node_material_parse["Material extraction<br/>[route.ts]"]
  node_agent_chat["Classroom agent chat<br/>[route.ts]"]
  node_agent_runtime["Agent runtime<br/>[route.ts]"]
end

subgraph group_platform["Persistence and integrations"]
  node_document_store[("Document store<br/>[index.ts]")]
  node_persistence_api["Persistence API<br/>[route.ts]"]
  node_server_storage[("Server persistence<br/>[server-provider.ts]")]
  node_settings["Provider settings<br/>[index.tsx]"]
end

node_learner(("Learner"))

node_learner -->|"requests course"| node_workbench
node_workbench -.->|"starts generation"| node_generation_api
node_generation_api -->|"runs pipeline"| node_run_engine
node_run_engine -.->|"reports progress"| node_run_status
node_run_engine -->|"persists classroom"| node_document_store
node_run_engine -->|"provides preview"| node_preview
node_learner -->|"uploads materials"| node_materials
node_materials -->|"parses attachments"| node_material_parse
node_learner -->|"opens lesson"| node_classroom
node_classroom -.->|"plays scenes"| node_playback
node_playback -->|"executes actions"| node_action_engine
node_learner -->|"edits classroom"| node_editor
node_classroom -.->|"renders PBL scenes"| node_pbl
node_learner -->|"asks questions"| node_agent_chat
node_agent_chat -.->|"uses agent runtime"| node_agent_runtime
node_learner -->|"exports classroom"| node_export
node_persistence_api -->|"reads and writes"| node_document_store
node_server_storage -->|"constructs store"| node_document_store
node_settings -.->|"configures models"| node_generation_api

click node_workbench "https://github.com/thu-maic/openmaic/blob/main/app/workbench/new/client.tsx"
click node_preview "https://github.com/thu-maic/openmaic/blob/main/app/generation-preview/page.tsx"
click node_generation_api "https://github.com/thu-maic/openmaic/blob/main/app/api/generate-classroom/route.ts"
click node_run_engine "https://github.com/thu-maic/openmaic/blob/main/lib/server/generation/run/engine.ts"
click node_run_status "https://github.com/thu-maic/openmaic/blob/main/app/api/generation-runs/%5Bid%5D/route.ts"
click node_materials "https://github.com/thu-maic/openmaic/blob/main/app/api/materials/route.ts"
click node_material_parse "https://github.com/thu-maic/openmaic/blob/main/app/api/materials/%5Bid%5D/extraction/route.ts"
click node_agent_chat "https://github.com/thu-maic/openmaic/blob/main/app/api/chat/pi/route.ts"
click node_agent_runtime "https://github.com/thu-maic/openmaic/blob/main/app/api/agent/runtime/route.ts"
click node_classroom "https://github.com/thu-maic/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx"
click node_playback "https://github.com/thu-maic/openmaic/blob/main/lib/playback/engine.ts"
click node_action_engine "https://github.com/thu-maic/openmaic/blob/main/lib/action/engine.ts"
click node_editor "https://github.com/thu-maic/openmaic/blob/main/components/edit/EditShell/EditShell.tsx"
click node_pbl "https://github.com/thu-maic/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx"
click node_export "https://github.com/thu-maic/openmaic/blob/main/lib/video-export/index.ts"
click node_document_store "https://github.com/thu-maic/openmaic/blob/main/lib/document-store/index.ts"
click node_persistence_api "https://github.com/thu-maic/openmaic/blob/main/app/api/persistence/%5B...path%5D/route.ts"
click node_server_storage "https://github.com/thu-maic/openmaic/blob/main/lib/persistence/server-provider.ts"
click node_settings "https://github.com/thu-maic/openmaic/blob/main/components/settings/index.tsx"

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_workbench,node_preview toneBlue
class node_generation_api,node_run_engine,node_run_status toneAmber
class node_classroom,node_playback,node_action_engine,node_editor,node_pbl,node_export toneMint
class node_materials,node_material_parse,node_agent_chat,node_agent_runtime toneRose
class node_document_store,node_persistence_api,node_server_storage,node_settings,node_learner toneIndigo
```

## Components

### Learner experience

- [Workbench request](https://github.com/thu-maic/openmaic/blob/main/app/workbench/new/client.tsx): `app/workbench/new/client.tsx`
- [Generation preview](https://github.com/thu-maic/openmaic/blob/main/app/generation-preview/page.tsx): `app/generation-preview/page.tsx`

### Generation

- [Generation API](https://github.com/thu-maic/openmaic/blob/main/app/api/generate-classroom/route.ts): `app/api/generate-classroom/route.ts`
- [Durable generation run](https://github.com/thu-maic/openmaic/blob/main/lib/server/generation/run/engine.ts): `lib/server/generation/run/engine.ts`
- [Run status and events](https://github.com/thu-maic/openmaic/blob/main/app/api/generation-runs/%5Bid%5D/route.ts): `app/api/generation-runs/[id]/route.ts`

### Classroom runtime

- [Classroom playback](https://github.com/thu-maic/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx): `app/classroom/[id]/page.tsx`
- [Playback engine](https://github.com/thu-maic/openmaic/blob/main/lib/playback/engine.ts): `lib/playback/engine.ts`
- [Action execution](https://github.com/thu-maic/openmaic/blob/main/lib/action/engine.ts): `lib/action/engine.ts`
- [Classroom editor](https://github.com/thu-maic/openmaic/blob/main/components/edit/EditShell/EditShell.tsx): `components/edit/EditShell/EditShell.tsx`
- [PBL experience](https://github.com/thu-maic/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx): `components/scene-renderers/pbl-renderer.tsx`
- [Classroom export](https://github.com/thu-maic/openmaic/blob/main/lib/video-export/index.ts): `lib/video-export/index.ts`

### Knowledge and agents

- [Material library](https://github.com/thu-maic/openmaic/blob/main/app/api/materials/route.ts): `app/api/materials/route.ts`
- [Material extraction](https://github.com/thu-maic/openmaic/blob/main/app/api/materials/%5Bid%5D/extraction/route.ts): `app/api/materials/[id]/extraction/route.ts`
- [Classroom agent chat](https://github.com/thu-maic/openmaic/blob/main/app/api/chat/pi/route.ts): `app/api/chat/pi/route.ts`
- [Agent runtime](https://github.com/thu-maic/openmaic/blob/main/app/api/agent/runtime/route.ts): `app/api/agent/runtime/route.ts`

### Persistence and integrations

- [Document store](https://github.com/thu-maic/openmaic/blob/main/lib/document-store/index.ts): `lib/document-store/index.ts`
- [Persistence API](https://github.com/thu-maic/openmaic/blob/main/app/api/persistence/%5B...path%5D/route.ts): `app/api/persistence/[...path]/route.ts`
- [Server persistence](https://github.com/thu-maic/openmaic/blob/main/lib/persistence/server-provider.ts): `lib/persistence/server-provider.ts`
- [Provider settings](https://github.com/thu-maic/openmaic/blob/main/components/settings/index.tsx): `components/settings/index.tsx`

### Other components

- **Learner**

## Connections

- Learner → Workbench request: requests course (evidence: `README.md`)
- Workbench request → Generation API: starts generation
- Generation API → Durable generation run: runs pipeline (evidence: `README.md`)
- Durable generation run → Run status and events: reports progress
- Durable generation run → Document store: persists classroom (evidence: `lib/server/generation/run/engine.ts`)
- Durable generation run → Generation preview: provides preview (evidence: `README.md`)
- Learner → Material library: uploads materials (evidence: `README.md`)
- Material library → Material extraction: parses attachments (evidence: `README.md`)
- Learner → Classroom playback: opens lesson (evidence: `README.md`)
- Classroom playback → Playback engine: plays scenes
- Playback engine → Action execution: executes actions (evidence: `lib/playback/engine.ts`)
- Learner → Classroom editor: edits classroom (evidence: `README.md`)
- Classroom playback → PBL experience: renders PBL scenes
- Learner → Classroom agent chat: asks questions (evidence: `README.md`)
- Classroom agent chat → Agent runtime: uses agent runtime
- Learner → Classroom export: exports classroom (evidence: `README.md`)
- Persistence API → Document store: reads and writes (evidence: `app/api/persistence/[...path]/route.ts`)
- Server persistence → Document store: constructs store (evidence: `lib/persistence/server-provider.ts`)
- Provider settings → Generation API: configures models
