# Main Layers in OpenMAIC Architecture: A Technical Deep Dive

> Explore the six main layers of OpenMAIC architecture: Generation Pipeline, Agent Runtime, Persistence Layer, Orchestration, Playback, and Action Engine for provider-neutral, multi-agent classrooms.

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

---

**OpenMAIC implements a modular six-layer architecture comprising the Generation Pipeline, Agent Runtime, Persistence Layer, Multi-Agent Orchestration, Playback Engine, and Action Engine, which together enable provider-neutral, multi-agent interactive classrooms.**

OpenMAIC (Open Multi-Agent Interactive Classroom) is an open-source platform designed for AI-driven education, built on a **loosely coupled, provider-neutral architecture**. The **main layers in OpenMAIC architecture** separate lesson creation, agent coordination, state management, and real-time execution into distinct, swappable components. This design enables features like one-click lesson generation, the Pro Workbench, and deep interactive mode while maintaining extensibility.

## Generation Pipeline

The **Generation Pipeline** handles two-stage lesson creation: first generating a structured outline, then converting each item into rich scenes containing slides, quizzes, simulations, or PBL content. Implemented in `packages/@openmaic/generation`, this layer produces data without execution concerns.

Key implementation details from the source:

- Primary entry point: `packages/@openmaic/generation/src/outline.ts`
- Main function: `generateOutline()`
- Supports model routing (e.g., `openai:gpt-5.5`) via environment variables

Example usage:

```typescript
import { generateOutline } from '@openmaic/generation';

const prompt = 'Teach me the basics of quantum mechanics';
const outline = await generateOutline(prompt, {
  model: 'openai:gpt-5.5',
});

console.log('Outline:', outline);

```

## Agent Runtime

The **Agent Runtime** provides durable, PostgreSQL-backed sessions that power the "agent workbench." Located in `lib/server/agent-runtime/`, this layer handles material upload, skill execution, and course-building tools while exposing a control-plane API at `/api/agent/*`.

Key implementation details:

- Session management: [`lib/server/agent-runtime/session.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/session.ts)
- Entry function: `startSession()`

Example:

```typescript
import { startSession } from '@openmaic/agent-runtime';

const session = await startSession({
  userId: 'anonymous',
  title: 'Quantum Mechanics 101',
});

console.log('Session ID:', session.id);

```

## Persistence Layer

The **Persistence Layer** offers swappable storage backends for documents, runtime state, key-value pairs, and binary assets. Located in `packages/@openmaic/storage`, it abstracts data location, allowing identical UI code to run in-browser or against PostgreSQL via `packages/@openmaic/storage/src/document-store.ts`.

By default, the system uses browser storage, with a PostgreSQL-backed implementation available for server deployments requiring durability.

## Multi-Agent Orchestration

The **Multi-Agent Orchestration** layer coordinates multiple AI agents using a LangGraph state-graph located in `lib/orchestration/`. A dedicated *director* node determines turn order, while the system streams events via Server-Sent Events (SSE).

Key file: [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts)

This layer sits atop the Agent Runtime, enabling agents to converse, decide the next speaker, and react to user input in real time.

## Playback Engine

The **Playback Engine** drives classroom playback through a state machine managing the lifecycle: idle → playing → live. Located in `lib/playback/`, it synchronizes actions (speech, whiteboard, spotlight) and reads persisted scene data to feed the UI.

Key implementation:

- Engine core: [`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts)
- Scene retrieval: `getScene()`

Example:

```typescript
import { getScene } from '@openmaic/playback';

const scene = await getScene({
  courseId: 'course-abc',
  sceneId: 'slide-3',
});

playScene(scene);

```

## Action Engine

The **Action Engine** executes over 28 concrete action types that agents emit during sessions. Located in `lib/action/`, it handles atomic operations including speech synthesis, whiteboard drawing, slide effects, and video playback.

Key implementation:

- Registry: [`lib/action/registry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/action/registry.ts)
- Function: `enqueueAction()`

Example:

```typescript
import { enqueueAction } from '@openmaic/action';

await enqueueAction({
  type: 'speech',
  payload: {
    text: 'Welcome to the quantum world!',
    voice: 'default',
  },
});

```

## Layer Interaction and Data Flow

The **OpenMAIC architecture** maintains strict separation of concerns:

- **Generation Pipeline** produces outline and scene payloads without execution logic
- **Agent Runtime** consumes generation data, persisting it via the Persistence Layer and exposing control APIs
- **Orchestration** manages agent conversation atop the runtime using LangGraph
- **Playback Engine** reads persisted scenes while the **Action Engine** renders atomic steps to the UI

## Summary

The **OpenMAIC architecture** divides the platform into six specialized layers:

- **Generation Pipeline** (`packages/@openmaic/generation`) creates lesson outlines and rich scenes via `generateOutline()`
- **Agent Runtime** (`lib/server/agent-runtime/`) manages durable PostgreSQL-backed sessions through `startSession()`
- **Persistence Layer** (`packages/@openmaic/storage`) abstracts document and state storage with swappable backends including [`document-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/document-store.ts)
- **Multi-Agent Orchestration** (`lib/orchestration/`) coordinates AI agents using LangGraph and a director node in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)
- **Playback Engine** (`lib/playback/`) drives the classroom state machine and retrieves scenes via `getScene()` in [`engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/engine.ts)
- **Action Engine** (`lib/action/`) executes 28+ action types including speech and whiteboard operations via `enqueueAction()` in [`registry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/registry.ts)

## Frequently Asked Questions

### What programming language is OpenMAIC built with?

OpenMAIC is primarily built with **TypeScript**. The codebase uses Node.js packages with paths like `packages/@openmaic/generation` and library folders under `lib/`, implementing the six-layer architecture with TypeScript interfaces and functions such as `generateOutline()` and `enqueueAction()`.

### How does the Generation Pipeline create lesson content?

The Generation Pipeline implements a **two-stage process**. First, it generates a structured outline from user prompts using `generateOutline()` in `packages/@openmaic/generation/src/outline.ts`. Then, it transforms each outline item into rich scenes containing slides, quizzes, or simulations, supporting model routing through providers like OpenAI.

### Can OpenMAIC run without a PostgreSQL database?

Yes. While the Agent Runtime uses PostgreSQL for durable sessions by default, the Persistence Layer supports **swappable backends**. The system can run entirely in-browser using browser storage for documents and runtime state, making it suitable for lightweight deployments without server infrastructure.

### What controls the sequence of agent actions during a live session?

The **Multi-Agent Orchestration** layer manages agent coordination using a LangGraph state-graph defined in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts). A dedicated *director* node determines turn order, while the Action Engine ([`lib/action/registry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/action/registry.ts)) executes the resulting 28+ action types that drive classroom interactions.