# How OpenMAIC Architecture Works: A Modular AI Classroom System

> Discover the OpenMAIC architecture a modular AI classroom system. Learn how Next.js LangGraph orchestrate LLM agents for dynamic content generation with pluggable services.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: architecture
- Published: 2026-09-08

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-tree.ts) defines the hierarchical tree model representing a session's structure, while [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts) handles in-memory session persistence. The React hook exported from [`lib/workbench/use-workbench-session.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/middleware.ts) handling global request processing. The **agent runtime**, implemented in [`lib/server/agent-runtime/entry-tree-storage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/tts-providers.ts), [`lib/audio/asr-providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/asr-providers.ts), and [`lib/media-parse/media-parse-providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) brings up the render container alongside the main application, while [`render-service/README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-tree.ts).

2. **Material Ingestion**: Uploaded documents, audio, and video files are processed through the **store layer** ([`lib/store/index.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) that abstract LLM, TTS, ASR, and image generation services. Provider-specific implementations in files like [`lib/audio/tts-providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/tts-providers.ts) and [`lib/audio/asr-providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/render-service/README.md).