How Core Business Logic Is Organized in OpenMAIC: The Three-Layer `lib/` Architecture

OpenMAIC’s core business logic is organized into three distinct layers within the lib/ package: Session & Workspace Management for persistence, Agent Runtime & Skill Loading for AI capabilities, and UI-Oriented Workbench components for stateless rendering.

OpenMAIC, an open-source project maintained by THU-MAIC, structures its core business logic within a carefully architected lib/ directory that separates concerns between client-side persistence, AI runtime operations, and presentation layers. This organization ensures that session state, agent capabilities, and user interface code remain decoupled while maintaining efficient data flow between client and server environments. Understanding how this core business logic is organized helps developers extend the platform’s AI capabilities or debug complex session management workflows.

Three-Layer Architecture in the lib/ Package

The business logic resides primarily in lib/workbench/ and lib/server/agent-runtime/, divided into three tightly-coupled but conceptually distinct layers.

Session and Workspace Management Layer

This layer tracks user conversations and persists session information across page loads. According to the OpenMAIC source code, the primary module lib/workbench/workspace-session-memory.ts handles client-side persistence using localStorage (lines 1-90). It provides functions like rememberWorkspaceSession() to store the last active session ID and readLastWorkspaceSessionId() to retrieve it when building resume links.

Server-side mutations live in lib/workbench/workspace-actions.ts, which exports Next.js Server Actions such as deleteWorkspaceSession() (lines 30-40). These functions act as a thin façade over the agent store, ensuring all database writes occur on the server while the client invokes them via type-safe server action calls.

Agent Runtime and Skill Loading Layer

The AI "agent" that powers chat functionality runs through the runtime layer centered at lib/server/agent-runtime/store.ts. This central store maintains sessions, handles soft-deletions via softDeleteSession(), and manages agent-specific data accessed by workspace-actions.ts.

Dynamic capability acquisition happens via lib/workbench/skill-load.ts, which lazy-loads skill modules the agent can invoke. This module handles caching and versioning, allowing the system to acquire new capabilities at runtime without requiring a client bundle rebuild.

UI-Oriented Workbench Layer

Rendering components reside in lib/workbench/ but remain "dumb"—they merely reflect state produced by the lower layers. Key files include:

• workspace-panes.ts - Composable components for chat and classroom views
• workspace-tree.ts - Hierarchical workspace layout data structures
• workspace-navigation.ts - Navigation state management
• workspace-order.ts - Pane ordering logic

These components subscribe to the Agent Runtime Store and render appropriate panes without directly accessing localStorage or performing database operations.

Data Flow Across the Business Logic Layers

The interaction between layers follows a strict unidirectional flow:

1. Initialization: When a user opens the app, workspace-session-memory.ts reads the last remembered session from localStorage.

2. Navigation: If a session ID exists, workspaceResumeHref() constructs the URL (/workspace?session=…) and navigates to the workspace page (pages/workspace.tsx).

3. State Hydration: The workspace page creates a workspace object that pulls the session from the Agent Runtime Store via getAgentSessionStore.

4. Rendering: UI components like WorkspaceChatPane and WorkspaceClassroomPane subscribe to the store and render content based on the current session state.

5. Mutations: User actions such as "Delete Session" trigger deleteWorkspaceSession() in workspace-actions.ts, which calls store.softDeleteSession() on the server, updates the store, and clears the remembered session from localStorage if needed.

6. Persistence: When opening new sessions, rememberWorkspaceSession() updates localStorage to enable resume functionality on subsequent page loads.

Key Architectural Patterns

Several patterns govern how core business logic is organized in OpenMAIC:

Separation of Concerns: Session persistence lives completely outside UI code. Components never write directly to localStorage; they only read session state from the store.

Server-Side Actions: The workspace-actions.ts module acts as a controlled gateway for mutations, keeping database writes server-side while exposing type-safe functions to the client.

Pluggable Skill System: The skill-load.ts implementation uses dynamic imports to load skill modules, decoupling agent capabilities from the core bundle.

Stateless UI Components: Workbench components are pure React components that re-render on store changes, making them easy to test without business logic side effects.

Implementation Examples

The following patterns demonstrate how to interact with OpenMAIC's business logic layers.

Remembering a workspace session after opening a chat:

import { rememberWorkspaceSession } from '@/lib/workbench/workspace-session-memory';

function onChatOpened(sessionId: string) {
  rememberWorkspaceSession(sessionId);
}

Building a resume link for the last session:

import { readLastWorkspaceSessionId, workspaceResumeHref } from '@/lib/workbench/workspace-session-memory';

function getResumeLink(): string {
  const lastId = readLastWorkspaceSessionId();
  return workspaceResumeHref(lastId);
}

Deleting a session via server action:

import { deleteWorkspaceSession } from '@/lib/workbench/workspace-actions';

async function onDelete(sessionId: string) {
  const { deleted } = await deleteWorkspaceSession(sessionId);
  if (deleted) alert('Session removed');
}

Summary

• OpenMAIC organizes core business logic into three layers within the lib/ package: Session Management (workspace-session-memory.ts), Agent Runtime (lib/server/agent-runtime/store.ts), and UI Workbench (workspace-panes.ts and related files).
• The workspace-session-memory.ts module handles client-side persistence via localStorage, while workspace-actions.ts manages server-side mutations through Next.js Server Actions.
• Dynamic skill loading occurs through skill-load.ts, enabling runtime capability extension without bundle rebuilds.
• UI components remain stateless, subscribing to the Agent Runtime Store rather than managing business logic directly.
• Data flows unidirectionally from localStorage initialization through server actions to reactive UI components.

Frequently Asked Questions

What is the role of workspace-session-memory.ts in OpenMAIC?

The lib/workbench/workspace-session-memory.ts file manages client-side session persistence by storing the last active conversation ID in the browser's localStorage. It exports functions like rememberWorkspaceSession() to save session state and readLastWorkspaceSessionId() to retrieve it, enabling the "resume workspace" functionality when users return to the application.

How does OpenMAIC handle skill loading dynamically?

OpenMAIC implements a pluggable skill system through lib/workbench/skill-load.ts, which lazy-loads skill modules that the AI agent can invoke. This module handles caching and versioning of skills, allowing the system to extend agent capabilities at runtime without requiring a complete client bundle rebuild or redeployment.

What is the difference between workspace-actions.ts and the agent runtime store?

lib/workbench/workspace-actions.ts contains Next.js Server Actions that act as a thin façade over the central store located at lib/server/agent-runtime/store.ts. While the store holds the actual session data and provides methods like softDeleteSession(), the actions file exposes type-safe server functions that UI components can invoke, ensuring all database mutations occur server-side while maintaining clear separation between client calls and data persistence logic.

How does the UI layer interact with business logic in OpenMAIC?

The UI layer in lib/workbench/ (including workspace-panes.ts, workspace-tree.ts, and navigation components) interacts with business logic through read-only subscription to the Agent Runtime Store. These components never write directly to localStorage or call database operations; instead, they render based on store state and delegate mutations to server actions in workspace-actions.ts, maintaining a strict separation between presentation and business logic.

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