Main Layers in OpenMAIC Architecture: A Technical Deep Dive

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:

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
• Entry function: startSession()

Example:

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

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
• Scene retrieval: getScene()

Example:

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
• Function: enqueueAction()

Example:

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
• Multi-Agent Orchestration (lib/orchestration/) coordinates AI agents using LangGraph and a director node in director-graph.ts
• Playback Engine (lib/playback/) drives the classroom state machine and retrieves scenes via getScene() in engine.ts
• Action Engine (lib/action/) executes 28+ action types including speech and whiteboard operations via enqueueAction() in 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. A dedicated director node determines turn order, while the Action Engine (lib/action/registry.ts) executes the resulting 28+ action types that drive classroom interactions.

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