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

> Discover how OpenMAIC organizes core business logic in its three-layer lib/ architecture: Session, Agent, and UI components. Understand its structure for efficient AI development.

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

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-actions.ts).

Dynamic capability acquisition happens via [`lib/workbench/skill-load.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-panes.ts)** - Composable components for chat and classroom views
- **[`workspace-tree.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-tree.ts)** - Hierarchical workspace layout data structures
- **[`workspace-navigation.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-navigation.ts)** - Navigation state management
- **[`workspace-order.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

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

```

Building a resume link for the last session:

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

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

```

Deleting a session via server action:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-session-memory.ts)), Agent Runtime ([`lib/server/agent-runtime/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/store.ts)), and UI Workbench ([`workspace-panes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-panes.ts) and related files).
- The [`workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-session-memory.ts) module handles client-side persistence via `localStorage`, while [`workspace-actions.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-actions.ts) manages server-side mutations through Next.js Server Actions.
- Dynamic skill loading occurs through [`skill-load.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-session-memory.ts) in OpenMAIC?

The [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-actions.ts) and the agent runtime store?

[`lib/workbench/workspace-actions.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-panes.ts), [`workspace-tree.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-actions.ts), maintaining a strict separation between presentation and business logic.