# maxthraxx/openmaic architecture

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

## Overview

OpenMAIC turns a learner’s topic or uploaded material into an interactive, multi-agent classroom, then supports live teaching, discussion, and export. The main path runs from the home-page generation experience through outline and scene generation into classroom playback. The README documents slides, quizzes, simulations, PBL, whiteboard/TTS, and PPTX/HTML export; those capability links are shown at the documented level. Source excerpts confirm pipeline staging and playback/action execution, but many UI and API implementations were not sampled.

Main entry points: [`app/classroom/[id]/page.tsx`](https://github.com/maxthraxx/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx) (Classroom view), [`app/page.tsx`](https://github.com/maxthraxx/openmaic/blob/main/app/page.tsx) (Creation workspace), [`components/stage/scene-renderer.tsx`](https://github.com/maxthraxx/openmaic/blob/main/components/stage/scene-renderer.tsx) (Scene rendering), [`lib/generation/pipeline-runner.ts`](https://github.com/maxthraxx/openmaic/blob/main/lib/generation/pipeline-runner.ts) (Generation pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Classroom creation"]
  node_home["Creation workspace<br/>[page.tsx]"]
  node_outlines["Outline generation"]
  node_pipeline["Generation pipeline<br/>[pipeline-runner.ts]"]
  node_scenes["Scene generation<br/>[scene-generator.ts]"]
end

subgraph group_runtime["Classroom runtime"]
  node_classroom["Classroom view<br/>[page.tsx]"]
  node_stage["Scene rendering<br/>[scene-renderer.tsx]"]
  node_roundtable["Agent discussion<br/>[index.tsx]"]
  node_playback["Lecture playback<br/>[engine.ts]"]
  node_actions["Agent action engine<br/>[engine.ts]"]
  node_whiteboard["Whiteboard<br/>[index.tsx]"]
  node_pbl["Project learning<br/>[pbl-renderer.tsx]"]
  node_quiz["Quiz scenes<br/>[quiz-renderer.tsx]"]
  node_interactive["Interactive scenes"]
  node_chat["Classroom chat<br/>[route.ts]"]
end

subgraph group_services["AI and media services"]
  node_pdf["Document parsing<br/>[route.ts]"]
  node_llm["LLM providers<br/>[providers.ts]"]
  node_media["Image and video"]
  node_speech["Speech services<br/>[tts-providers.ts]"]
  node_websearch["Web search<br/>[tavily.ts]"]
end

subgraph group_state["Classroom state and export"]
  node_storage[("Classroom storage")]
  node_browserdata[("Browser persistence<br/>[database.ts]")]
  node_export["Classroom export"]
  node_pptx["PPTX export<br/>[use-export-pptx.ts]"]
end

node_learner(("Learner"))

node_learner -->|"describes topic"| node_home
node_home -.->|"submits materials"| node_pdf
node_home -.->|"starts generation"| node_pipeline
node_pipeline -->|"generates outlines"| node_outlines
node_pipeline -->|"generates scenes"| node_scenes
node_scenes -->|"produces classroom"| node_classroom
node_classroom -.->|"renders scenes"| node_stage
node_classroom -->|"hosts discussion"| node_roundtable
node_classroom -.->|"plays lecture"| node_playback
node_playback -->|"executes actions"| node_actions
node_actions -->|"draws content"| node_whiteboard
node_stage -->|"renders PBL"| node_pbl
node_stage -->|"renders quizzes"| node_quiz
node_stage -->|"renders simulations"| node_interactive
node_roundtable -->|"speaks aloud"| node_speech
node_roundtable -->|"draws diagrams"| node_whiteboard
node_learner -->|"sends message"| node_chat
node_chat -->|"requests response"| node_llm
node_learner -.->|"requests media"| node_media
node_learner -.->|"searches topic"| node_websearch
node_classroom -.->|"loads classroom"| node_storage
node_home -.->|"persists settings"| node_browserdata
node_classroom -->|"exports HTML"| node_export
node_classroom -->|"exports slides"| node_pptx

click node_home "https://github.com/maxthraxx/openmaic/blob/main/app/page.tsx"
click node_pdf "https://github.com/maxthraxx/openmaic/blob/main/app/api/parse-pdf/route.ts"
click node_outlines "https://github.com/maxthraxx/openmaic/blob/main/lib/generation/outline-generator.ts"
click node_pipeline "https://github.com/maxthraxx/openmaic/blob/main/lib/generation/pipeline-runner.ts"
click node_scenes "https://github.com/maxthraxx/openmaic/blob/main/lib/generation/scene-generator.ts"
click node_classroom "https://github.com/maxthraxx/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx"
click node_stage "https://github.com/maxthraxx/openmaic/blob/main/components/stage/scene-renderer.tsx"
click node_roundtable "https://github.com/maxthraxx/openmaic/blob/main/components/roundtable/index.tsx"
click node_playback "https://github.com/maxthraxx/openmaic/blob/main/lib/playback/engine.ts"
click node_actions "https://github.com/maxthraxx/openmaic/blob/main/lib/action/engine.ts"
click node_whiteboard "https://github.com/maxthraxx/openmaic/blob/main/components/whiteboard/index.tsx"
click node_pbl "https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx"
click node_quiz "https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/quiz-renderer.tsx"
click node_interactive "https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/interactive-renderer.tsx"
click node_chat "https://github.com/maxthraxx/openmaic/blob/main/app/api/chat/route.ts"
click node_llm "https://github.com/maxthraxx/openmaic/blob/main/lib/ai/providers.ts"
click node_media "https://github.com/maxthraxx/openmaic/blob/main/lib/media/media-orchestrator.ts"
click node_speech "https://github.com/maxthraxx/openmaic/blob/main/lib/audio/tts-providers.ts"
click node_websearch "https://github.com/maxthraxx/openmaic/blob/main/lib/web-search/tavily.ts"
click node_storage "https://github.com/maxthraxx/openmaic/blob/main/lib/server/classroom-storage.ts"
click node_browserdata "https://github.com/maxthraxx/openmaic/blob/main/lib/utils/database.ts"
click node_export "https://github.com/maxthraxx/openmaic/blob/main/lib/export/use-export-classroom.ts"
click node_pptx "https://github.com/maxthraxx/openmaic/blob/main/lib/export/use-export-pptx.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_home,node_outlines,node_pipeline,node_scenes toneBlue
class node_classroom,node_stage,node_roundtable,node_playback,node_actions,node_whiteboard,node_pbl,node_quiz,node_interactive,node_chat toneAmber
class node_pdf,node_llm,node_media,node_speech,node_websearch toneMint
class node_storage,node_browserdata,node_export,node_pptx toneRose
class node_learner toneIndigo
```

## Components

### Classroom creation

- [Creation workspace](https://github.com/maxthraxx/openmaic/blob/main/app/page.tsx): `app/page.tsx`
- [Outline generation](https://github.com/maxthraxx/openmaic/blob/main/lib/generation/outline-generator.ts): `lib/generation/outline-generator.ts`
- [Generation pipeline](https://github.com/maxthraxx/openmaic/blob/main/lib/generation/pipeline-runner.ts): `lib/generation/pipeline-runner.ts`
- [Scene generation](https://github.com/maxthraxx/openmaic/blob/main/lib/generation/scene-generator.ts): `lib/generation/scene-generator.ts`

### Classroom runtime

- [Classroom view](https://github.com/maxthraxx/openmaic/blob/main/app/classroom/%5Bid%5D/page.tsx): `app/classroom/[id]/page.tsx`
- [Scene rendering](https://github.com/maxthraxx/openmaic/blob/main/components/stage/scene-renderer.tsx): `components/stage/scene-renderer.tsx`
- [Agent discussion](https://github.com/maxthraxx/openmaic/blob/main/components/roundtable/index.tsx): `components/roundtable/index.tsx`
- [Lecture playback](https://github.com/maxthraxx/openmaic/blob/main/lib/playback/engine.ts): `lib/playback/engine.ts`
- [Agent action engine](https://github.com/maxthraxx/openmaic/blob/main/lib/action/engine.ts): `lib/action/engine.ts`
- [Whiteboard](https://github.com/maxthraxx/openmaic/blob/main/components/whiteboard/index.tsx): `components/whiteboard/index.tsx`
- [Project learning](https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/pbl-renderer.tsx): `components/scene-renderers/pbl-renderer.tsx`
- [Quiz scenes](https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/quiz-renderer.tsx): `components/scene-renderers/quiz-renderer.tsx`
- [Interactive scenes](https://github.com/maxthraxx/openmaic/blob/main/components/scene-renderers/interactive-renderer.tsx): `components/scene-renderers/interactive-renderer.tsx`
- [Classroom chat](https://github.com/maxthraxx/openmaic/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`

### AI and media services

- [Document parsing](https://github.com/maxthraxx/openmaic/blob/main/app/api/parse-pdf/route.ts): `app/api/parse-pdf/route.ts`
- [LLM providers](https://github.com/maxthraxx/openmaic/blob/main/lib/ai/providers.ts): `lib/ai/providers.ts`
- [Image and video](https://github.com/maxthraxx/openmaic/blob/main/lib/media/media-orchestrator.ts): `lib/media/media-orchestrator.ts`
- [Speech services](https://github.com/maxthraxx/openmaic/blob/main/lib/audio/tts-providers.ts): `lib/audio/tts-providers.ts`
- [Web search](https://github.com/maxthraxx/openmaic/blob/main/lib/web-search/tavily.ts): `lib/web-search/tavily.ts`

### Classroom state and export

- [Classroom storage](https://github.com/maxthraxx/openmaic/blob/main/lib/server/classroom-storage.ts): `lib/server/classroom-storage.ts`
- [Browser persistence](https://github.com/maxthraxx/openmaic/blob/main/lib/utils/database.ts): `lib/utils/database.ts`
- [Classroom export](https://github.com/maxthraxx/openmaic/blob/main/lib/export/use-export-classroom.ts): `lib/export/use-export-classroom.ts`
- [PPTX export](https://github.com/maxthraxx/openmaic/blob/main/lib/export/use-export-pptx.ts): `lib/export/use-export-pptx.ts`

### Other components

- **Learner**

## Connections

- Learner → Creation workspace: describes topic (evidence: `README.md`)
- Creation workspace → Document parsing: submits materials
- Creation workspace → Generation pipeline: starts generation
- Generation pipeline → Outline generation: generates outlines (evidence: `lib/generation/pipeline-runner.ts`)
- Generation pipeline → Scene generation: generates scenes (evidence: `lib/generation/pipeline-runner.ts`)
- Scene generation → Classroom view: produces classroom (evidence: `README.md`)
- Classroom view → Scene rendering: renders scenes
- Classroom view → Agent discussion: hosts discussion (evidence: `README.md`)
- Classroom view → Lecture playback: plays lecture
- Lecture playback → Agent action engine: executes actions (evidence: `lib/playback/engine.ts`)
- Agent action engine → Whiteboard: draws content (evidence: `lib/action/engine.ts`)
- Scene rendering → Project learning: renders PBL (evidence: `README.md`)
- Scene rendering → Quiz scenes: renders quizzes (evidence: `README.md`)
- Scene rendering → Interactive scenes: renders simulations (evidence: `README.md`)
- Agent discussion → Speech services: speaks aloud (evidence: `README.md`)
- Agent discussion → Whiteboard: draws diagrams (evidence: `README.md`)
- Learner → Classroom chat: sends message (evidence: `README.md`)
- Classroom chat → LLM providers: requests response (evidence: `app/api/chat/route.ts`)
- Learner → Image and video: requests media
- Learner → Web search: searches topic
- Classroom view → Classroom storage: loads classroom
- Creation workspace → Browser persistence: persists settings
- Classroom view → Classroom export: exports HTML (evidence: `README.md`)
- Classroom view → PPTX export: exports slides (evidence: `README.md`)