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

> Explore the OpenMAIC architecture layers: Generation Pipeline, Agent Runtime, Storage, Orchestration, Playback, Action, and UI. Understand this modular AI education stack for flexible, interactive experiences.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-02

---

**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](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md#L77) 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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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/](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md#L77) at lines 77-86. Below are practical initialization examples for core components:

### Initializing the Storage Layer

Configure browser-first storage with optional PostgreSQL fallback:

```typescript
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:

```typescript
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:

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

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

```

### Using the Playback Engine

Drive classroom presentations with timeline synchronization:

```typescript
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](https://github.com/THU-MAIC/OpenMAIC/tree/main/packages/@openmaic/generation)
- **Agent Runtime** maintains durable PostgreSQL-backed execution sessions via [lib/server/agent-runtime](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/server/agent-runtime)
- **Storage Layer** abstracts persistence across browser, HTTP, PostgreSQL, and S3 backends in [packages/@openmaic/storage](https://github.com/THU-MAIC/OpenMAIC/tree/main/packages/@openmaic/storage)
- **Multi-Agent Orchestration** coordinates complex agent interactions via LangGraph in [lib/orchestration](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/orchestration)
- **Playback Engine** manages real-time classroom timeline and state synchronization from [lib/playback](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/playback)
- **Action Engine** executes 28+ specialized interaction types defined in [lib/action](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/action)
- **Presentation UI** renders the complete interactive learning interface via [components/](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/playback) engine manages timeline progression and triggers action events, which the [lib/action](https://github.com/THU-MAIC/OpenMAIC/tree/main/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](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md#L77) 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](https://github.com/THU-MAIC/OpenMAIC/tree/main/packages/@openmaic/generation) for content creation and [lib/server/agent-runtime](https://github.com/THU-MAIC/OpenMAIC/tree/main/lib/server/agent-runtime) for session management.