How OpenMAIC Architecture Works: A Modular AI Classroom System

OpenMAIC is a modular, front-end + back-end + agent runtime system built on Next.js that orchestrates LLM agents via LangGraph to generate AI-driven classroom content, featuring pluggable providers for LLM, TTS, ASR, and optional video rendering services.

The OpenMAIC architecture powers an extensible platform for creating interactive educational content through AI agents. Developed by THU-MAIC and hosted in the THU-MAIC/OpenMAIC repository, this system separates concerns between the React-based workbench UI, a stateful session layer, and a provider-agnostic agent runtime. Understanding how these layers interact reveals why the architecture supports everything from single-process development to multi-node production deployments.

Core Architectural Layers of OpenMAIC

User Interface Layer (Next.js Frontend)

The presentation layer is a Next.js application using React and Tailwind CSS that hosts the interactive workbench. The entry point for user sessions is located in app/workspace/page.tsx, which renders the main workspace interface where educators upload materials and interact with generated courses. Styling definitions in components/workbench/workspace-shell.css ensure consistent UI behavior across the workbench panes.

Workbench and Session Management

The client-side workbench manages session state, navigation, and skill loading through a durable session store that synchronizes with the back-end. At the core of this layer, lib/workbench/workspace-tree.ts defines the hierarchical tree model representing a session's structure, while lib/workbench/workspace-session-memory.ts handles in-memory session persistence. The React hook exported from lib/workbench/use-workbench-session.ts drives the UI state, enabling real-time updates as the agent runtime produces new content.

API Server and Agent Runtime

The Next.js API routes serve as the bridge between the UI and the core AI logic, with middleware.ts handling global request processing. The agent runtime, implemented in lib/server/agent-runtime/entry-tree-storage.ts, constitutes the heart of OpenMAIC. It uses LangGraph to orchestrate multiple LLM agents, interpreting prompts and generating a hierarchical Intermediate Representation (IR) consisting of Instructions, Scenes, and Assets. This runtime is deliberately provider-neutral, allowing any OpenAI-compatible LLM, AWS Bedrock, or local model to be plugged in through configuration.

Provider Plugins and Abstractions

OpenMAIC abstracts all external AI services behind unified interfaces defined in lib/ai/providers.ts. This single file declares common contracts for LLM, TTS (Text-to-Speech), ASR (Automatic Speech Recognition), and image generation services. Concrete implementations reside in specialized adapters such as lib/audio/tts-providers.ts, lib/audio/asr-providers.ts, and lib/media-parse/media-parse-providers.ts, making it straightforward to add new vendors without modifying core logic.

Render Service and Export Pipeline

For multimedia output, a separate Docker-compose service converts generated HTML and slide content into MP4 videos. Configuration in docker-compose.yml brings up the render container alongside the main application, while render-service/README.md documents deployment procedures. If the render service is unavailable, the server gracefully falls back to generating a ZIP export that users can process locally using the CLI tool.

SDK Packages for Programmatic Access

The architecture exposes public NPM packages under the @openmaic/* namespace, enabling programmatic interaction with the generation pipeline. The packages/@openmaic/generation/package.json defines the core generation SDK, while packages/@openmaic/dsl/src/slides.ts contains the Domain Specific Language (DSL) definitions for slide content. Additional utilities like packages/@openmaic/importer/src/serializer/textSerializer.ts handle bidirectional conversion between HTML and DSL formats.

Data Flow Through the OpenMAIC Architecture

The system processes educational content creation through a specific pipeline:

1. Session Initialization: When a user starts a session in the browser, the workbench UI generates a unique session ID and initializes an empty session tree via workspace-tree.ts.

2. Material Ingestion: Uploaded documents, audio, and video files are processed through the store layer (lib/store/index.ts), which persists assets and registers them in the session state. The pluggable store implementation supports in-memory maps for development or PostgreSQL for production.

3. Agent Orchestration: User prompts (e.g., "Teach me quantum physics") trigger API calls to the agent runtime, which constructs a scene-graph (IR) describing the course structure.

4. Provider Invocation: The runtime calls the configured LLM provider through the unified interface, optionally invoking TTS, ASR, or image providers to generate multimedia assets.

5. State Synchronization: The generated IR persists through the store layer, and the workbench UI receives the updated tree to render new slides, quizzes, or interactive HTML components via use-workbench-session.ts.

6. Export and Rendering: Upon export request, the server submits assets to the render service at the configured RENDER_SERVICE_URL to compose MP4 videos, or generates a ZIP package for local CLI rendering if the service is disabled.

Programmatic Usage with the OpenMAIC SDK

Developers can interact with the architecture directly through the public SDK without running the full UI. The following example demonstrates generating a course programmatically:

// Install dependencies: pnpm add @openmaic/generation @openmaic/dsl

import { generateCourse } from '@openmaic/generation';
import { Slide } from '@openmaic/dsl';

const prompt = 'Create a short lesson on photosynthesis with 3 slides and a quiz.';

async function main() {
  // Communicates with the configured LLM provider via the agent runtime
  const course = await generateCourse({ prompt });
  
  // Access the generated DSL objects
  console.log('Generated slides:', course.scenes.filter(s => s.type === 'slide'));
  
  // Render to HTML for external use
  const html = Slide.render(course.scenes);
  console.log('HTML output:', html);
}

main().catch(console.error);

This example requires at least one provider API key configured in .env.local, as the SDK internally calls the agent runtime through the server API and returns a course object following the same IR used by the workbench UI.

Summary

• OpenMAIC implements a three-tier architecture separating the Next.js UI, stateful workbench, and LangGraph-based agent runtime.
• The provider-neutral design in lib/ai/providers.ts enables swapping between OpenAI, Bedrock, or local LLMs without code changes.
• Session persistence is handled through a pluggable store layer (lib/store/index.ts) supporting both in-memory development mode and PostgreSQL production deployments.
• The agent runtime generates hierarchical IR (Instruction → Scene → Asset) that the workbench renders as interactive educational content.
• Optional video rendering runs as a separate Docker service defined in docker-compose.yml, with ZIP fallback for offline processing.
• Public SDK packages (@openmaic/generation) allow external tools to leverage the same generation pipeline as the web UI.

Frequently Asked Questions

What technology stack underpins the OpenMAIC architecture?

The system is built on Next.js with React and Tailwind CSS for the frontend, while the backend API and agent runtime run within the same Next.js application using API routes. The agent orchestration relies on LangGraph to manage multi-step LLM workflows, and the entire stack can be deployed via Docker Compose with an optional render service for video generation.

How does OpenMAIC support different AI providers without vendor lock-in?

The architecture defines unified interfaces in lib/ai/providers.ts that abstract LLM, TTS, ASR, and image generation services. Provider-specific implementations in files like lib/audio/tts-providers.ts and lib/audio/asr-providers.ts adhere to these contracts, allowing developers to swap between OpenAI-compatible APIs, AWS Bedrock, or local models by changing configuration rather than core logic.

What storage backends can be used with OpenMAIC?

The store layer defined in lib/store/index.ts supports multiple persistence strategies through a pluggable interface. Deployments can use simple in-memory storage for development and testing, or scale to production using PostgreSQL or custom backend implementations. This flexibility enables both single-process development environments and multi-node production clusters with shared state.

How does the rendering pipeline work for video export?

When users request video export, the server sends generated assets to a dedicated render service (configured via RENDER_SERVICE_URL) that composes MP4 files from HTML and slide content. If this Docker service is unavailable, the system automatically generates a ZIP package containing all necessary assets, which users can render locally using the OpenMAIC CLI tool. The render service deployment is documented in render-service/README.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}