OpenMAIC Platform Architecture: A Modular Multi-Agent Classroom System

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, 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 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 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 handles course grouping and folder hierarchy
• Pane management – workspace-panes.ts and workspace-rail-tab.ts manage state, drag-and-drop, and pagination
• Session persistence – session-store.ts and material-upload-scheduling.ts coordinate durable metadata and asset uploads
• Runtime integration – tts-stage-sync.ts and 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 – 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 – Persists stage state and incremental updates to PostgreSQL with atomic write guarantees
• 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 provides atomic writes, incremental persistence, and a drain mechanism for background cleanup coordination.

Media assets upload through policies defined in 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 file. At runtime, 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) – Conditionally renders the Pro badge based on public feature flags
• Generation toolbar (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, 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)

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

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

Initializing a Durable Server Session

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

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

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
• Agent runtime executes multi-agent workflows via 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.

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 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.

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