# shashwatphd-ai/openmaicsyllabus architecture

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

- Interactive diagram: https://gitdiagram.com/shashwatphd-ai/openmaicsyllabus
- Repository: https://github.com/shashwatphd-ai/openmaicsyllabus

## Overview

1. **Overall shape**
   - OpenMAIC is a **Next.js 16 / React 19 / TypeScript** monorepo that mixes a browser UI with a substantial server-side orchestration layer.
   - The app is organized around a core workflow: **user input → lesson generation → classroom playback/interactions → export or reuse**.

2. **Primary user-facing surfaces**
   - `app/page.tsx` is the main entry for generating a classroom from a topic or document.
   - `app/classroom/[id]/page.tsx` is the runtime classroom experience for a generated lesson.
   - `app/generation-preview/` is a separate inspection/debug surface for generation outputs.

3. **Server boundary: API-driven architecture**
   - Most backend behavior lives in `app/api/*` route handlers.
   - Key clusters are:
     - `generate/*` for lesson creation steps
     - `generate-classroom/*` for async classroom jobs and polling
     - `chat/*` and `pbl/chat/*` for streaming agent conversations
     - media, PDF, transcription, web search, and provider verification endpoints
   - The frontend talks to these routes rather than directly to provider SDKs, which keeps provider logic behind a server boundary.

4. **Lesson generation pipeline**
   - `lib/generation/` contains the main two-stage pipeline described in the README:
     - **outline generation**
     - **scene/content generation**
   - Supporting pieces include prompt templates, JSON repair, action parsing, and a pipeline runner.
   - The output of this layer feeds classroom scenes such as slides, quizzes, interactive simulations, and PBL activities.

5. **Multi-agent orchestration**
   - `lib/orchestration/` implements the director-style agent flow using **LangGraph**.
   - This layer builds prompts, manages tool schemas, and coordinates stateless generation as well as director-driven interactions.
   - It is the main decision-making layer for “who speaks next” and “what action should happen next” in classroom discussion modes.

6. **Playback and action execution**
   - `lib/playback/` is the state machine that drives classroom presentation state.
   - `lib/action/engine.ts` executes classroom actions such as speech, highlighting, drawing, spotlight/laser effects, and other presentation behaviors.
   - `components/stage/`, `components/roundtable/`, and `components/whiteboard/` are the interactive presentation surfaces that consume this state.

7. **Scene renderers and classroom modes**
   - `components/scene-renderers/` splits the runtime classroom into distinct modes:
     - quiz renderer
     - interactive renderer
     - PBL renderer
   - `components/stage/scene-renderer.tsx` and related stage components appear to be the integration point that chooses which scene type is active.
   - This is an important architectural boundary: one generation pipeline feeds multiple runtime scene systems.

8. **Slide editing and rich content rendering**
   - `components/slide-renderer/` is a large canvas/editor subsystem for slide layout and rendering.
   - It supports multiple element types: text, image, shapes, tables, charts, LaTeX, lines, and video.
   - The corresponding configuration in `configs/` defines shared rendering behavior for fonts, shapes, lines, hotkeys, themes, and storage-related defaults.

9. **Provider abstraction layer**
   - `lib/ai/`, `lib/audio/`, `lib/media/`, `lib/pdf/`, and `lib/web-search/` isolate external capabilities behind provider adapters.
   - This repository supports multiple backends for:
     - LLMs
     - TTS and ASR
     - image/video generation
     - PDF parsing
     - web search
   - The `app/api/verify-*` and `app/api/server-providers` routes suggest a runtime model where provider configuration is validated and resolved server-side before use.

10. **Data storage and state management**
   - Client state is mostly in `lib/store/` with Zustand-based stores for stage, canvas, settings, user profile, history, and media generation.
   - Persistence helpers live in `lib/utils/*-storage.ts`, and the repository includes a `noop` storage provider in `lib/storage/providers/`, implying storage is pluggable and may run without a real backend.
   - `lib/contexts/` and `lib/hooks/` wire these stores into React components.

11. **Classroom media and document handling**
   - `app/api/classroom-media/[classroomId]/[...path]/route.ts` and `lib/server/classroom-media-generation.ts` indicate generated assets are organized per classroom and served back through a dedicated media layer.
   - `app/api/parse-pdf` plus `lib/pdf/` and the optional MinerU integration show document ingestion is a first-class input path, especially for complex PDFs.
   - `app/api/proxy-media` and `lib/server/proxy-fetch.ts` suggest controlled fetching/proxying of remote assets.

12. **OpenClaw integration**
   - The `skills/openmaic/` directory is not part of runtime classroom execution; it is an **operator integration layer** for external assistants like OpenClaw.
   - Its job is to guide setup, invocation, and async generation workflows from chat platforms, then poll the OpenMAIC backend until a classroom is ready.
   - This creates a second entry path into the system besides the web UI.

13. **Export and packaging**
   - `lib/export/` supports outputting classrooms as editable **PPTX** and interactive **HTML**.
   - The repo includes custom workspace packages for `pptxgenjs` and `mathml2omml`, which are important because they handle Office document generation and math conversion without relying entirely on upstream packages.

14. **Repository-level infrastructure**
   - The app is prepared for container and hosted deployment via `Dockerfile`, `docker-compose.yml`, `vercel.json`, and GitHub Actions CI.
   - E2E tests in `e2e/` cover the main user journeys: home-to-generation, generation flow, and classroom interaction.
   - This makes the architecture “frontend + server routes + orchestration libraries + provider adapters + interactive rendering,” rather than a simple single-page app.

Main entry points: [`lib/generation/generation-pipeline.ts`](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/generation/generation-pipeline.ts) (Pipeline), [`lib/export/use-export-pptx.ts`](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/export/use-export-pptx.ts) (Export), [`lib/orchestration/director-graph.ts`](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/director-graph.ts) (Director), [`lib/orchestration/stateless-generate.ts`](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/stateless-generate.ts) (Chat flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App surfaces"]
  node_home["Home<br/>Next page<br/>[page.tsx]"]
  node_classroom["Classroom<br/>Next page<br/>[page.tsx]"]
  node_preview["Preview<br/>Next page<br/>[page.tsx]"]
end

subgraph group_api["API routes"]
  node_api_routes["APIs<br/>route cluster"]
end

subgraph group_core["Core generation"]
  node_gen_pipeline["Pipeline"]
  node_prompting["Prompts<br/>prompt system<br/>[index.ts]"]
  node_director["Director<br/>LangGraph orchestration<br/>[director-graph.ts]"]
  node_chat_orch["Chat flow<br/>agent orchestration"]
  node_job_runner["Jobs"]
end

subgraph group_runtime["Runtime UI"]
  node_playback["Playback<br/>state machine<br/>[engine.ts]"]
  node_action_engine["Actions<br/>presentation engine<br/>[engine.ts]"]
  node_scene_switch["Scene switch<br/>scene router<br/>[scene-renderer.tsx]"]
  node_stage_ui["Stage UI<br/>classroom stage<br/>[stage.tsx]"]
  node_slide_editor["Slide editor<br/>canvas editor<br/>[index.tsx]"]
end

subgraph group_providers["Providers"]
  node_media_layer["Media layer<br/>provider adapters"]
  node_ai_core["LLM core<br/>LLM adapters<br/>[llm.ts]"]
  node_pdf_core["PDF ingest<br/>document parsing<br/>[pdf-providers.ts]"]
end

subgraph group_storage["State and export"]
  node_store["Client store<br/>Zustand state<br/>[index.ts]"]
  node_exporter["Export<br/>[use-export-pptx.ts]"]
end

subgraph group_packages["Workspace packages"]
  node_pptx_pkg["PPTX pkg<br/>workspace package<br/>[pptxgen.ts]"]
  node_mathml_pkg["MathML pkg<br/>workspace package<br/>[index.js]"]
end

subgraph group_ops["Integration layer"]
  node_openmaic_skill["OpenClaw skill<br/>operator guide<br/>[SKILL.md]"]
end

node_home -->|"generate"| node_api_routes
node_api_routes -->|"lesson flow"| node_gen_pipeline
node_api_routes -->|"chat"| node_chat_orch
node_api_routes -->|"async jobs"| node_job_runner
node_api_routes -->|"media"| node_media_layer
node_api_routes -->|"parse pdf"| node_pdf_core
node_gen_pipeline -->|"templates"| node_prompting
node_gen_pipeline -->|"orchestrate"| node_director
node_director -->|"model calls"| node_ai_core
node_chat_orch -->|"streaming"| node_ai_core
node_job_runner -->|"persist"| node_store
node_classroom -->|"play"| node_stage_ui
node_stage_ui -->|"render scene"| node_scene_switch
node_scene_switch -->|"state"| node_playback
node_playback -->|"execute"| node_action_engine
node_action_engine -->|"visuals"| node_slide_editor
node_slide_editor -->|"ui state"| node_store
node_exporter -->|"pptx"| node_pptx_pkg
node_exporter -->|"math"| node_mathml_pkg
node_openmaic_skill -.->|"invoke"| node_api_routes
node_preview -->|"inspect"| node_api_routes
node_media_layer -->|"serve assets"| node_api_routes

click node_home "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/page.tsx"
click node_classroom "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/classroom/[id]/page.tsx"
click node_preview "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/generation-preview/page.tsx"
click node_gen_pipeline "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/generation/generation-pipeline.ts"
click node_prompting "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/generation/prompts/index.ts"
click node_director "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/director-graph.ts"
click node_chat_orch "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/stateless-generate.ts"
click node_job_runner "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/server/classroom-job-runner.ts"
click node_playback "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/playback/engine.ts"
click node_action_engine "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/action/engine.ts"
click node_scene_switch "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/stage/scene-renderer.tsx"
click node_stage_ui "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/stage.tsx"
click node_slide_editor "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/slide-renderer/Editor/index.tsx"
click node_media_layer "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/media/media-orchestrator.ts"
click node_ai_core "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/ai/llm.ts"
click node_pdf_core "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/pdf/pdf-providers.ts"
click node_store "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/store/index.ts"
click node_exporter "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/export/use-export-pptx.ts"
click node_pptx_pkg "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/packages/pptxgenjs/src/pptxgen.ts"
click node_mathml_pkg "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/packages/mathml2omml/src/index.js"
click node_openmaic_skill "https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/skills/openmaic/SKILL.md"

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_classroom,node_preview,node_pptx_pkg,node_mathml_pkg toneBlue
class node_api_routes,node_openmaic_skill toneAmber
class node_gen_pipeline,node_prompting,node_director,node_chat_orch,node_job_runner toneMint
class node_playback,node_action_engine,node_scene_switch,node_stage_ui,node_slide_editor toneRose
class node_media_layer,node_ai_core,node_pdf_core toneIndigo
class node_store,node_exporter toneTeal
```

## Components

### App surfaces

Primary browser entry points and UX surfaces.

- [Home](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/page.tsx): Next page · Main lesson creation entrypoint. · `app/page.tsx`
- [Classroom](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/classroom/[id]/page.tsx): Next page · Runtime lesson playback experience. · `app/classroom/[id]/page.tsx`
- [Preview](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/app/generation-preview/page.tsx): Next page · Generation inspection and debugging surface. · `app/generation-preview/page.tsx`

### API routes

Server-side route handlers that expose backend capabilities.

- **APIs**: route cluster · Generation, chat, media, PDF, search, verification, and job routes.

### Core generation

Lesson generation, orchestration, playback, and classroom job control.

- [Pipeline](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/generation/generation-pipeline.ts): generation pipeline · Outline and scene/content generation flow. · `lib/generation/generation-pipeline.ts`
- [Prompts](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/generation/prompts/index.ts): prompt system · Template loading, formatting, and repair helpers for generation. · `lib/generation/prompts/index.ts`
- [Director](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/director-graph.ts): LangGraph orchestration · Multi-agent decision layer for stateless and directed interactions. · `lib/orchestration/director-graph.ts`
- [Chat flow](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/orchestration/stateless-generate.ts): agent orchestration · Streaming chat and director-driven conversation plumbing. · `lib/orchestration/stateless-generate.ts`
- [Jobs](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/server/classroom-job-runner.ts): classroom jobs · Async classroom generation, storage, and polling lifecycle. · `lib/server/classroom-job-runner.ts`

### Runtime UI

Classroom playback, scene rendering, and interactive editing surfaces.

- [Playback](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/playback/engine.ts): state machine · Classroom presentation state and derived runtime state. · `lib/playback/engine.ts`
- [Actions](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/action/engine.ts): presentation engine · Executes speech, highlight, drawing, and spotlight actions. · `lib/action/engine.ts`
- [Scene switch](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/stage/scene-renderer.tsx): scene router · Chooses quiz, interactive, or PBL scene renderer at runtime. · `components/stage/scene-renderer.tsx`
- [Stage UI](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/stage.tsx): classroom stage · Main presentation surface and surrounding classroom controls. · `components/stage.tsx`
- [Slide editor](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/components/slide-renderer/Editor/index.tsx): canvas editor · Rich slide layout and element editing subsystem. · `components/slide-renderer/Editor/index.tsx`

### Providers

Abstraction layers for AI, media, PDF, audio, and search backends.

- [Media layer](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/media/media-orchestrator.ts): provider adapters · LLM, TTS/ASR, image/video, PDF, and search integrations. · `lib/media/media-orchestrator.ts`
- [LLM core](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/ai/llm.ts): LLM adapters · Model abstraction and provider resolution. · `lib/ai/llm.ts`
- [PDF ingest](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/pdf/pdf-providers.ts): document parsing · PDF provider abstraction and parsing support. · `lib/pdf/pdf-providers.ts`

### State and export

Client state, persistence, and export pipelines.

- [Client store](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/store/index.ts): Zustand state · Stage, canvas, settings, history, and media generation state. · `lib/store/index.ts`
- [Export](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/lib/export/use-export-pptx.ts): export pipeline · HTML and PPTX export pathways. · `lib/export/use-export-pptx.ts`

### Workspace packages

Custom package implementations vendored into the monorepo.

- [PPTX pkg](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/packages/pptxgenjs/src/pptxgen.ts): workspace package · Vendored PPTX generation implementation. · `packages/pptxgenjs/src/pptxgen.ts`
- [MathML pkg](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/packages/mathml2omml/src/index.js): workspace package · MathML to OMML conversion package. · `packages/mathml2omml/src/index.js`

### Integration layer

External assistant/operator entry points and workflow guides.

- [OpenClaw skill](https://github.com/shashwatphd-ai/openmaicsyllabus/blob/main/skills/openmaic/SKILL.md): operator guide · External assistant integration for setup, invocation, and async polling. · `skills/openmaic/SKILL.md`

## Connections

- Home → APIs: generate · Submits topics/documents and starts lesson creation.
- APIs → Pipeline: lesson flow · Routes call into the generation pipeline and scene builders.
- APIs → Chat flow: chat · Streams agent conversations and director interactions.
- APIs → Jobs: async jobs · Starts and polls classroom generation jobs.
- APIs → Media layer: media · Proxy for image, video, audio, and search providers.
- APIs → PDF ingest: parse pdf · Handles document ingestion and PDF provider checks.
- Pipeline → Prompts: templates · Builds prompts and repairs structured output.
- Pipeline → Director: orchestrate · Feeds generated scenes into agent-driven workflows.
- Director → LLM core: model calls · Uses LLM adapters to choose next actions and speakers.
- Chat flow → LLM core: streaming · Backed by model provider abstractions.
- Jobs → Client store: persist · Writes classroom/job state and metadata.
- Classroom → Stage UI: play · Mounts the runtime classroom experience.
- Stage UI → Scene switch: render scene · Selects the active scene renderer.
- Scene switch → Playback: state · Consumes playback state for scene presentation.
- Playback → Actions: execute · Turns state transitions into presentation actions.
- Actions → Slide editor: visuals · Drives slides, overlays, and interactive canvas behavior.
- Slide editor → Client store: ui state · Relies on shared canvas and settings stores.
- Export → PPTX pkg: pptx · Uses the workspace PPTX generator implementation.
- Export → MathML pkg: math · Converts equation content for Office export.
- OpenClaw skill → APIs: invoke · External operator flow targets backend generation endpoints.
- Preview → APIs: inspect · Reads generation outputs through API-backed data.
- Media layer → APIs: serve assets · Generated media is exposed back through server routes.
