OpenMAIC Architecture Layers: A Deep Dive into the Modular AI Education Stack

The OpenMAIC architecture consists of seven independent layers—Generation Pipeline, Agent Runtime, Storage Layer, Multi-Agent Orchestration, Playback Engine, Action Engine, and Presentation UI—that enable durable, flexible, and interactive AI-driven teaching experiences.

The THU-MAIC/OpenMAIC repository implements a modular, layer-based architecture designed to separate concerns between content creation, agent execution, state persistence, and real-time classroom interaction. Understanding these OpenMAIC architecture layers is essential for developers extending the platform or integrating custom providers. Each layer is deliberately isolated according to the Key Architecture section of the README, allowing you to swap implementations without affecting other system components.

Layer 1: Generation Pipeline

The Generation Pipeline handles two-stage lesson creation, transforming high-level outlines into detailed scene content. This layer resides in the packages/@openmaic/generation directory and operates independently of runtime execution, enabling batch or on-demand content generation workflows.

Layer 2: Agent Runtime

The Agent Runtime provides durable, PostgreSQL-backed sessions that power the Pro workbench. According to the lib/server/agent-runtime implementation, this layer manages execution contexts, session leasing, resume/steer capabilities, and skill handling. The runtime ensures that agent state survives server restarts through persistent database connections configured via the startAgentRuntime function.

Layer 3: Storage Layer

The Storage Layer offers swappable storage abstractions for documents, runtime state, assets, and key-value pairs. Implemented in the packages/@openmaic/storage package, this layer supports multiple backends including browser localStorage, HTTP APIs, PostgreSQL, and S3. The architecture allows runtime switching between these backends through factory functions like createDocumentStore and createRuntimeStore.

Layer 4: Multi-Agent Orchestration

The Multi-Agent Orchestration layer coordinates complex interactions between multiple AI agents using a LangGraph state machine. Located in lib/orchestration, this component manages turn-taking, state transitions, and inter-agent communication protocols through the directorGraph implementation.

Layer 5: Playback Engine

The Playback Engine drives classroom playback and live interactions through a dedicated state machine. Found in lib/playback, this layer synchronizes slide transitions, audio timing, and interactive timelines during lesson delivery via the PlaybackEngine class.

Layer 6: Action Engine

The Action Engine executes over 28 distinct action types including speech synthesis, whiteboard drawing, spotlight effects, and laser pointer controls. The implementation in lib/action processes action queues and translates high-level commands into specific UI behaviors, decoupling the timeline logic from execution details.

Layer 7: Presentation UI

The Presentation UI layer comprises React components and UI helpers that render slides, quizzes, interactive scenes, and the workbench interface. Located in components/ and supporting library directories, this layer consumes outputs from the Generation Pipeline and Playback Engine while sending user inputs back to the Agent Runtime.

Working with the Architecture

The high-level architecture diagram and layer descriptions are documented in the repository's README.md at lines 77-86. Below are practical initialization examples for core components:

Initializing the Storage Layer

Configure browser-first storage with optional PostgreSQL fallback:

import { createDocumentStore } from '@openmaic/storage/document';
import { createRuntimeStore } from '@openmaic/storage/runtime';

// Browser storage (default)
const docStore = createDocumentStore();          // ↳ lib/persistence/browser.ts
const runtimeStore = createRuntimeStore();       // ↳ lib/persistence/runtime-browser.ts

// When NEXT_PUBLIC_PERSISTENCE=1, the same factories will point to the HTTP‑backed PostgreSQL implementation

Starting an Agent Runtime Session

Create durable sessions that survive server restarts:

import { startAgentRuntime } from '@/lib/server/agent-runtime';

await startAgentRuntime({
  databaseUrl: process.env.DATABASE_URL!,
  modelRoutes: JSON.parse(process.env.MODEL_ROUTES!),
});

Executing Multi-Agent Orchestration

Run the LangGraph director for coordinated agent workflows:

import { directorGraph } from '@/lib/orchestration';

await directorGraph.run({
  input: { topic: 'Quantum Mechanics' },
});

Using the Playback Engine

Drive classroom presentations with timeline synchronization:

import { PlaybackEngine } from '@/lib/playback';

const engine = new PlaybackEngine({
  courseId: 'abc123',
  onSpeechStart: () => console.log('Speaker started'),
});

engine.play();

Summary

The OpenMAIC architecture layers provide clear separation of concerns for building AI-native educational applications:

• Generation Pipeline creates lesson content through outline-to-scene transformation in packages/@openmaic/generation
• Agent Runtime maintains durable PostgreSQL-backed execution sessions via lib/server/agent-runtime
• Storage Layer abstracts persistence across browser, HTTP, PostgreSQL, and S3 backends in packages/@openmaic/storage
• Multi-Agent Orchestration coordinates complex agent interactions via LangGraph in lib/orchestration
• Playback Engine manages real-time classroom timeline and state synchronization from lib/playback
• Action Engine executes 28+ specialized interaction types defined in lib/action
• Presentation UI renders the complete interactive learning interface via components/

Frequently Asked Questions

What is the relationship between the Agent Runtime and the Storage Layer?

The Agent Runtime depends on the Storage Layer for durability but remains loosely coupled through interface abstractions. The runtime uses storage primitives to persist session state, execution checkpoints, and skill configurations, allowing you to swap database backends from browser storage to PostgreSQL without modifying runtime logic in lib/server/agent-runtime.

How does the Multi-Agent Orchestration layer handle agent state?

The orchestration layer uses LangGraph to maintain explicit state machines for multi-agent conversations. Each agent's turn, context window, and intermediate outputs are tracked as graph state nodes in lib/orchestration, enabling deterministic replay and human-in-the-loop steering at specific checkpoints through the directorGraph.run method.

Can the Playback Engine operate independently of the Action Engine?

While the Playback Engine and Action Engine are separate layers, they typically work together during live sessions. The lib/playback engine manages timeline progression and triggers action events, which the lib/action engine then executes. However, you can use the playback engine in simulation mode without invoking UI actions, or trigger actions manually without the playback timeline for testing purposes.

Where is the architecture documented in the source code?

The canonical architecture overview appears in the README.md file at lines 77-86, which describes the layer relationships and design philosophy. Each layer's implementation details are contained within the specific file paths referenced throughout this article, such as packages/@openmaic/generation for content creation and lib/server/agent-runtime for session management.

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