How shashwatphd-ai/openmaicsyllabus works
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: generation-pipeline.ts Pipeline · use-export-pptx.ts Export · director-graph.ts Director · stateless-generate.ts Chat flow
Components 22
App surfaces
Primary browser entry points and UX surfaces.
API routes
Server-side route handlers that expose backend capabilities.
- APIs · Generation, chat, media, PDF, search, verification, and job routes.
Core generation
Lesson generation, orchestration, playback, and classroom job control.
- Pipeline · Outline and scene/content generation flow.
lib/generation/generation-pipeline.ts - Prompts · Template loading, formatting, and repair helpers for generation.
lib/generation/prompts/index.ts - Director · Multi-agent decision layer for stateless and directed interactions.
lib/orchestration/director-graph.ts - Chat flow · Streaming chat and director-driven conversation plumbing.
lib/orchestration/stateless-generate.ts - 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 · Classroom presentation state and derived runtime state.
lib/playback/engine.ts - Actions · Executes speech, highlight, drawing, and spotlight actions.
lib/action/engine.ts - Scene switch · Chooses quiz, interactive, or PBL scene renderer at runtime.
components/stage/scene-renderer.tsx - Stage UI · Main presentation surface and surrounding classroom controls.
components/stage.tsx - Slide 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 · LLM, TTS/ASR, image/video, PDF, and search integrations.
lib/media/media-orchestrator.ts - LLM core · Model abstraction and provider resolution.
lib/ai/llm.ts - PDF ingest · PDF provider abstraction and parsing support.
lib/pdf/pdf-providers.ts
State and export
Client state, persistence, and export pipelines.
- Client store · Stage, canvas, settings, history, and media generation state.
lib/store/index.ts - Export · HTML and PPTX export pathways.
lib/export/use-export-pptx.ts
Workspace packages
Custom package implementations vendored into the monorepo.
- PPTX pkg · Vendored PPTX generation implementation.
packages/pptxgenjs/src/pptxgen.ts - MathML pkg · MathML to OMML conversion package.
packages/mathml2omml/src/index.js
Integration layer
External assistant/operator entry points and workflow guides.
- OpenClaw skill · External assistant integration for setup, invocation, and async polling.
skills/openmaic/SKILL.md
Connections 22
- 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.