# github4kid/openmaic architecture

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

## Overview

OpenMAIC is an AI-powered interactive classroom and course-building platform. Its main journey is to provide a topic or learning materials, generate a course of scenes and activities, edit or steer that course, then present it as an interactive classroom with agent discussion and playback. The README also describes a Pro workbench with durable sessions, reusable skills, and configurable model, media, search, and storage providers. Edges use README-level capability statements where implementation wiring was not sampled; unsampled details are intentionally not inferred.

Main entry points: [`app/classroom/[id]/page.tsx`](https://github.com/github4kid/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx) (Classroom View), [`components/stage.tsx`](https://github.com/github4kid/openmaic/blob/main/components/stage.tsx) (Stage Editor), [`app/generation-preview/page.tsx`](https://github.com/github4kid/openmaic/blob/main/app/generation-preview/page.tsx) (Course Generator), [`app/workbench/new/client.tsx`](https://github.com/github4kid/openmaic/blob/main/app/workbench/new/client.tsx) (Agent Workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Course Creation"]
  node_generator["Course Generator<br/>[page.tsx]"]
  node_outline["Outline Generation<br/>[route.ts]"]
  node_material["Document Extraction<br/>[route.ts]"]
end

subgraph group_agent["Agent Workbench"]
  node_workbench["Agent Workbench<br/>[client.tsx]"]
  node_agent_runtime["Agent Runtime<br/>[lifecycle.ts]"]
  node_sessions["Durable Sessions<br/>[route.ts]"]
  node_skills["Course Skills<br/>[route.ts]"]
end

subgraph group_authoring["Course Authoring"]
  node_stage_editor["Stage Editor<br/>[stage.tsx]"]
  node_slide_editor["Slide Editing<br/>[index.tsx]"]
  node_action_engine["Action Engine<br/>[engine.ts]"]
  node_stage_data["Stage Data<br/>[stage.ts]"]
end

subgraph group_classroom["Learning Experience"]
  node_classroom["Classroom View<br/>[page.tsx]"]
  node_scene_renderer["Scene Renderer<br/>[scene-renderer.tsx]"]
  node_playback["Playback Engine<br/>[engine.ts]"]
  node_roundtable["Live Discussion<br/>[index.tsx]"]
  node_pbl["Project Learning<br/>[pbl-renderer.tsx]"]
  node_chat[("Chat Sessions<br/>[chat-storage.ts]")]
end

subgraph group_platform["Runtime Services"]
  node_provider_settings["Provider Settings<br/>[settings.ts]"]
  node_runtime_store[("Runtime Storage<br/>[store.ts]")]
  node_stage_storage[("Stage Persistence<br/>[stage-storage.ts]")]
  node_video_export["Video Export<br/>[route.ts]"]
end

node_learner(("Learner / Author"))

node_learner -->|"starts generation"| node_generator
node_generator -->|"requests outlines"| node_outline
node_learner -->|"provides materials"| node_material
node_learner -->|"steers course"| node_workbench
node_workbench -->|"delegates building"| node_agent_runtime
node_workbench -->|"uses durable runs"| node_sessions
node_agent_runtime -->|"uses course tools"| node_skills
node_agent_runtime -->|"builds from materials"| node_material
node_generator -->|"creates course"| node_stage_editor
node_stage_editor -->|"edits scenes"| node_stage_data
node_stage_editor -->|"provides editing"| node_slide_editor
node_learner -->|"opens course"| node_classroom
node_classroom -->|"presents scenes"| node_scene_renderer
node_classroom -->|"runs actions"| node_playback
node_playback -->|"executes actions"| node_action_engine
node_classroom -->|"hosts discussions"| node_roundtable
node_classroom -->|"presents projects"| node_pbl
node_roundtable -.->|"persists sessions"| node_chat
node_provider_settings -.->|"configures providers"| node_generator
node_stage_editor -.->|"saves course"| node_stage_storage
node_learner -->|"requests export"| node_video_export
node_stage_storage -.->|"uses runtime storage"| node_runtime_store

click node_generator "https://github.com/github4kid/openmaic/blob/main/app/generation-preview/page.tsx"
click node_outline "https://github.com/github4kid/openmaic/blob/main/app/api/generate/scene-outlines-stream/route.ts"
click node_material "https://github.com/github4kid/openmaic/blob/main/app/api/extract-document/route.ts"
click node_workbench "https://github.com/github4kid/openmaic/blob/main/app/workbench/new/client.tsx"
click node_agent_runtime "https://github.com/github4kid/openmaic/blob/main/lib/agent-runtime/lifecycle.ts"
click node_sessions "https://github.com/github4kid/openmaic/blob/main/app/api/agent/sessions/route.ts"
click node_skills "https://github.com/github4kid/openmaic/blob/main/app/api/agent/skills/route.ts"
click node_stage_editor "https://github.com/github4kid/openmaic/blob/main/components/stage.tsx"
click node_slide_editor "https://github.com/github4kid/openmaic/blob/main/components/slide-renderer/Editor/index.tsx"
click node_action_engine "https://github.com/github4kid/openmaic/blob/main/lib/action/engine.ts"
click node_stage_data "https://github.com/github4kid/openmaic/blob/main/lib/types/stage.ts"
click node_classroom "https://github.com/github4kid/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx"
click node_scene_renderer "https://github.com/github4kid/openmaic/blob/main/components/stage/scene-renderer.tsx"
click node_playback "https://github.com/github4kid/openmaic/blob/main/lib/playback/engine.ts"
click node_roundtable "https://github.com/github4kid/openmaic/blob/main/components/roundtable/index.tsx"
click node_pbl "https://github.com/github4kid/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx"
click node_chat "https://github.com/github4kid/openmaic/blob/main/lib/utils/chat-storage.ts"
click node_provider_settings "https://github.com/github4kid/openmaic/blob/main/lib/store/settings.ts"
click node_runtime_store "https://github.com/github4kid/openmaic/blob/main/lib/runtime/store.ts"
click node_stage_storage "https://github.com/github4kid/openmaic/blob/main/lib/utils/stage-storage.ts"
click node_video_export "https://github.com/github4kid/openmaic/blob/main/app/api/export-video/render/route.ts"

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_generator,node_outline,node_material toneBlue
class node_workbench,node_agent_runtime,node_sessions,node_skills toneAmber
class node_stage_editor,node_slide_editor,node_action_engine,node_stage_data toneMint
class node_classroom,node_scene_renderer,node_playback,node_roundtable,node_pbl,node_chat toneRose
class node_provider_settings,node_runtime_store,node_stage_storage,node_video_export,node_learner toneIndigo
```

## Components

### Course Creation

- [Course Generator](https://github.com/github4kid/openmaic/blob/main/app/generation-preview/page.tsx): `app/generation-preview/page.tsx`
- [Outline Generation](https://github.com/github4kid/openmaic/blob/main/app/api/generate/scene-outlines-stream/route.ts): `app/api/generate/scene-outlines-stream/route.ts`
- [Document Extraction](https://github.com/github4kid/openmaic/blob/main/app/api/extract-document/route.ts): `app/api/extract-document/route.ts`

### Agent Workbench

- [Agent Workbench](https://github.com/github4kid/openmaic/blob/main/app/workbench/new/client.tsx): `app/workbench/new/client.tsx`
- [Agent Runtime](https://github.com/github4kid/openmaic/blob/main/lib/agent-runtime/lifecycle.ts): `lib/agent-runtime/lifecycle.ts`
- [Durable Sessions](https://github.com/github4kid/openmaic/blob/main/app/api/agent/sessions/route.ts): `app/api/agent/sessions/route.ts`
- [Course Skills](https://github.com/github4kid/openmaic/blob/main/app/api/agent/skills/route.ts): `app/api/agent/skills/route.ts`

### Course Authoring

- [Stage Editor](https://github.com/github4kid/openmaic/blob/main/components/stage.tsx): `components/stage.tsx`
- [Slide Editing](https://github.com/github4kid/openmaic/blob/main/components/slide-renderer/Editor/index.tsx): `components/slide-renderer/Editor/index.tsx`
- [Action Engine](https://github.com/github4kid/openmaic/blob/main/lib/action/engine.ts): `lib/action/engine.ts`
- [Stage Data](https://github.com/github4kid/openmaic/blob/main/lib/types/stage.ts): `lib/types/stage.ts`

### Learning Experience

- [Classroom View](https://github.com/github4kid/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx): `app/classroom/[id]/page.tsx`
- [Scene Renderer](https://github.com/github4kid/openmaic/blob/main/components/stage/scene-renderer.tsx): `components/stage/scene-renderer.tsx`
- [Playback Engine](https://github.com/github4kid/openmaic/blob/main/lib/playback/engine.ts): `lib/playback/engine.ts`
- [Live Discussion](https://github.com/github4kid/openmaic/blob/main/components/roundtable/index.tsx): `components/roundtable/index.tsx`
- [Project Learning](https://github.com/github4kid/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx): `components/scene-renderers/pbl-renderer.tsx`
- [Chat Sessions](https://github.com/github4kid/openmaic/blob/main/lib/utils/chat-storage.ts): `lib/utils/chat-storage.ts`

### Runtime Services

- [Provider Settings](https://github.com/github4kid/openmaic/blob/main/lib/store/settings.ts): `lib/store/settings.ts`
- [Runtime Storage](https://github.com/github4kid/openmaic/blob/main/lib/runtime/store.ts): `lib/runtime/store.ts`
- [Stage Persistence](https://github.com/github4kid/openmaic/blob/main/lib/utils/stage-storage.ts): `lib/utils/stage-storage.ts`
- [Video Export](https://github.com/github4kid/openmaic/blob/main/app/api/export-video/render/route.ts): `app/api/export-video/render/route.ts`

### Other components

- **Learner / Author**

## Connections

- Learner / Author → Course Generator: starts generation (evidence: `README.md`)
- Course Generator → Outline Generation: requests outlines (evidence: `README.md`)
- Learner / Author → Document Extraction: provides materials (evidence: `README.md`)
- Learner / Author → Agent Workbench: steers course (evidence: `README.md`)
- Agent Workbench → Agent Runtime: delegates building (evidence: `README.md`)
- Agent Workbench → Durable Sessions: uses durable runs (evidence: `README.md`)
- Agent Runtime → Course Skills: uses course tools (evidence: `README.md`)
- Agent Runtime → Document Extraction: builds from materials (evidence: `README.md`)
- Course Generator → Stage Editor: creates course (evidence: `README.md`)
- Stage Editor → Stage Data: edits scenes (evidence: `README.md`)
- Stage Editor → Slide Editing: provides editing (evidence: `README.md`)
- Learner / Author → Classroom View: opens course (evidence: `README.md`)
- Classroom View → Scene Renderer: presents scenes (evidence: `README.md`)
- Classroom View → Playback Engine: runs actions (evidence: `lib/playback/engine.ts`)
- Playback Engine → Action Engine: executes actions (evidence: `lib/playback/engine.ts`)
- Classroom View → Live Discussion: hosts discussions (evidence: `README.md`)
- Classroom View → Project Learning: presents projects (evidence: `README.md`)
- Live Discussion → Chat Sessions: persists sessions
- Provider Settings → Course Generator: configures providers
- Stage Editor → Stage Persistence: saves course
- Learner / Author → Video Export: requests export (evidence: `README.md`)
- Stage Persistence → Runtime Storage: uses runtime storage (evidence: `lib/utils/stage-storage.ts`)