# OpenMAIC Platform Architecture: A Modular Multi-Agent Classroom System

> Explore the OpenMAIC platform architecture, a modular multi-agent system. Discover its provider-neutral design, separating UI from AI orchestration for robust classroom solutions.

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

---

**OpenMAIC combines a Next.js 16 frontend with a durable server-side agent runtime to deliver a provider-neutral, feature-flagged architecture that separates UI concerns from heavy-duty AI orchestration.**

OpenMAIC (Open Multi-Agent Interactive Classroom) is an extensible platform designed for creating AI-driven educational content through collaborative multi-agent workflows. Built with **React 19**, **TypeScript 5**, and **LangGraph 1.1**, the codebase emphasizes clean separation between client-side interactions and server-side execution. This examination of the OpenMAIC platform architecture reveals how modular design enables pluggable LLM providers, durable session persistence, and extensible skill systems.

## Feature-Flag Layer for Build and Runtime Control

OpenMAIC employs a dual-layer feature-flag system to manage visibility across environments.

### Public and Server-Only Flags

**Public flags** prefixed with `NEXT_PUBLIC_*` are inlined into the client bundle at build time. These enable UI-level toggles such as the Pro workbench badge displayed in the header. **Server-only flags** prefixed with `OPENMAIC_*` protect sensitive configuration including runtime enablement and database URLs.

The central configuration lives in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts), which exposes boolean gates like `isProWorkbenchEnabled()` and `isAgentRuntimeConfigured()`. These helpers validate environment variables and determine platform capabilities without exposing secrets to the browser.

## Entry-Gate and Routing Protection

All workbench entry points under `/workspace` and `/api/...` route through [`lib/workbench/entry-gate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/entry-gate.ts) before rendering. The `isWorkbenchEntryEnabled()` function combines the **public Pro flag** with the **runtime configuration flag** to ensure both client support and server capability exist.

If either flag returns false, the gate redirects requests to the home page, preventing users from accessing a half-functional workspace. This pattern ensures that features requiring database persistence or LLM configuration cannot be accessed until properly provisioned.

## Pro Workbench UI Layer

The professional workspace is implemented as a dynamic Next.js route in [`app/workspace/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/workspace/page.tsx) using `export const dynamic = 'force-dynamic'`. This forces feature-flag checks on every request rather than at build time, enabling runtime configuration changes without redeployment.

The page loads the `<WorkspaceEntry />` component, which hosts a multi-pane IDE supported by pure TypeScript utilities under `lib/workbench/`:

- **Navigation tree** – [`workspace-tree.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-tree.ts) handles course grouping and folder hierarchy
- **Pane management** – [`workspace-panes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-panes.ts) and [`workspace-rail-tab.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-rail-tab.ts) manage state, drag-and-drop, and pagination
- **Session persistence** – [`session-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/session-store.ts) and [`material-upload-scheduling.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/material-upload-scheduling.ts) coordinate durable metadata and asset uploads
- **Runtime integration** – [`tts-stage-sync.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tts-stage-sync.ts) and [`stage-freshness.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stage-freshness.ts) handle streaming updates from the agent runtime

These modules contain **no fetch or React code**, allowing comprehensive unit testing outside the browser environment.

## Agent-Runtime Execution Engine

The **agent-runtime** serves as the platform's brain, orchestrating multi-agent interactions, tool execution, and curriculum generation entirely on the server. Located under `lib/server/agent-runtime/`, the runtime is gated by `isAgentRuntimeEnabled()` and requires a valid `DATABASE_URL`.

Key architectural components include:

- **[`runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/runner.ts)** – Executes stages, tracks tool calls, and streams results to the client via persistent connections
- **`tools/`** – Definitions for generation, DSL parsing, material-media processing, and voice-clone operations
- **`skills/`** – Directory of **skill markdown files** (`*.md`) describing reusable tool bundles
- **[`store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/store.ts)** – Persists stage state and incremental updates to PostgreSQL with atomic write guarantees
- **[`lifecycle.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lifecycle.ts)** – Emits events for stage start/finish, enabling real-time UI feedback

The runtime implements a **provider-neutral** architecture through the `ModelProvider` interface. Thin adapters for OpenAI, Anthropic, Bedrock, and other providers conform to this contract, allowing seamless swapping without modifying core orchestration logic.

## Persistence and Storage Architecture

OpenMAIC stores session data, stage artifacts, and media in **PostgreSQL**, configured via the `DATABASE_URL` environment variable. The storage layer in [`lib/runtime/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/runtime/store.ts) provides atomic writes, incremental persistence, and a **drain** mechanism for background cleanup coordination.

Media assets upload through policies defined in [`material-upload-policy.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/material-upload-policy.ts) and are referenced by UUIDs stored within session documents. The platform supports **local AI providers** such as Lemonade or FunASR via configurable base URLs, enabling fully offline deployments without cloud dependencies.

## Markdown-Driven Skill System

Skills are **declarative specifications** located under `skills/agent-runtime/`. Each skill bundles tool names and optional prompts within a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) file. At runtime, [`skill-preload.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skill-preload.ts) validates and loads these specifications into the **tool-call registry**.

This design enables contributors to add capabilities by dropping markdown files into the skills directory without modifying core TypeScript code. The system dynamically registers new tools during the agent initialization phase.

## Frontend Component Architecture

The UI layer leverages **Tailwind CSS** for styling and organizes components under `components/generation/` and `ui/`. High-level responsibilities include:

- **Header navigation** ([`components/header.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/header.tsx)) – Conditionally renders the Pro badge based on public feature flags
- **Generation toolbar** ([`components/generation/generation-toolbar.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/generation/generation-toolbar.tsx)) – Triggers one-click lesson generation and workspace transitions
- **Interactive media** – Popover components for inserting slides, quizzes, and simulations

Components consume the **workspace context** through React hooks like `useWorkbenchSession` to maintain synchronization with server-side state.

## Deployment and Runtime Configuration

OpenMAIC targets **Vercel** serverless deployments via [`vercel.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/vercel.json), which declares API routes for the runtime. For on-premise installations, the `Dockerfile` provides a reproducible container environment.

Environment configuration in `.env.example` exposes all configurable knobs including LLM API keys, database connections, and feature toggles, supporting both cloud-hosted and air-gapped deployments.

## Practical Implementation Examples

### Checking Pro Workbench Availability (Client Side)

```typescript
import { isProWorkbenchEnabled } from '@/lib/config/feature-flags';

if (isProWorkbenchEnabled()) {
  // Render "Open Pro Workspace" button
}

```

### Initializing a Durable Server Session

```typescript
import { startSession } from '@/lib/server/agent-runtime/runner';
import { getAgentRuntimeConfig } from '@/lib/server/agent-runtime/config';

const config = getAgentRuntimeConfig();
const session = await startSession({
  model: config.defaultModel,
  materials: ['https://example.com/syllabus.pdf'],
});

```

### Loading Custom Skills at Runtime

```typescript
import { loadSkill } from '@/lib/server/agent-runtime/skills';
import { join } from 'path';

const skillPath = join(process.cwd(), 'skills/agent-runtime', 'curriculum-design', 'SKILL.md');
const skill = await loadSkill(skillPath);
console.log('Available tools:', skill.tools);

```

### Grouping Courses for Navigation Trees

```typescript
import { groupCoursesByFolder } from '@/lib/workbench/workspace-tree';

const courses = [{ id: 'c1', name: 'Intro', folderId: 'f1' }];
const folders = [{ id: 'f1', name: 'Module 1' }];

const tree = groupCoursesByFolder(courses, folders);

```

## Summary

- **OpenMAIC** separates client UI (`app/workspace/`), feature-flag configuration (`lib/config/`), and server-side agent runtime (`lib/server/agent-runtime/`) into distinct layers
- **Feature flags** control build-time bundling and runtime access through environment variables in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts)
- **Agent runtime** executes multi-agent workflows via [`runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/runner.ts) with pluggable LLM providers and PostgreSQL persistence
- **Skill system** enables runtime extensibility through markdown specifications in `skills/agent-runtime/` without code changes
- **Deployment flexibility** supports Vercel serverless or Dockerized on-premise installations with local AI provider support

## Frequently Asked Questions

### What technologies power the OpenMAIC platform?

OpenMAIC is built with **Next.js 16**, **React 19**, **TypeScript 5**, and **LangGraph 1.1**. The frontend uses Tailwind CSS for styling, while the backend relies on PostgreSQL for persistence and supports multiple LLM providers through adapter interfaces.

### How does OpenMAIC handle different LLM providers?

The platform implements a **provider-neutral** architecture through the `ModelProvider` interface in the agent runtime. Thin adapters for OpenAI, Anthropic, Azure, and Bedrock conform to this contract, allowing seamless provider swapping by changing environment variables without modifying orchestration logic in [`lib/server/agent-runtime/runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/runner.ts).

### Can OpenMAIC be deployed offline or on-premises?

Yes. OpenMAIC supports fully offline deployments through its Docker containerization and configurable local AI providers. By setting custom base URLs for services like Lemonade or FunASR in the environment configuration, organizations can run the platform without cloud dependencies while maintaining full functionality.

### What is the purpose of the skill system in OpenMAIC?

The **skill system** provides extensible, markdown-driven tool bundles located under `skills/agent-runtime/`. Each [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) file defines reusable tool sets that the agent runtime loads and validates at startup, enabling contributors to add new capabilities by adding documentation files rather than modifying core TypeScript code.