# Understanding the Monorepo Structure of OpenMAIC: A Complete Guide

> Explore the OpenMAIC monorepo structure. Learn how pnpm, apps, packages, configs, and components streamline Next.js frontend, AI agent libraries, and shared configs.

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

---

**OpenMAIC uses a pnpm-based monorepo architecture with `apps/`, `packages/@openmaic/*`, `configs/`, and `components/` directories, enabling centralized management of the Next.js frontend, reusable AI agent libraries, and shared configuration files.**

The monorepo structure of OpenMAIC organizes all frontend, backend, and shared libraries needed for the AI agent platform into a single cohesive workspace. This pnpm workspace configuration allows the THU-MAIC team to publish scoped packages under `@openmaic/*` while maintaining atomic versioning and dependency management across the entire ecosystem. Understanding this layout is essential for developers contributing to the agent logic, skill plugins, or web interface.

## Top-Level Directory Layout

The repository root follows standard pnpm workspace conventions, separating runnable applications from reusable libraries and configuration files.

- **`apps/`** – Contains standalone runnable applications, primarily the Next.js web interface at [`apps/web/app/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/apps/web/app/page.tsx)
- **`packages/`** – Houses all publishable libraries under the `@openmaic/*` npm scope
- **`configs/`** – Centralized configuration files including [`configs/theme.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/configs/theme.ts) for theming and hotkey definitions
- **`components/`** – UI components that are not published as packages but consumed by the web app, such as [`components/workbench/workspace/WorkspaceShell.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/workbench/workspace/WorkspaceShell.tsx)
- **`e2e/`** – Playwright end-to-end test suites located in [`e2e/tests/full-happy-path.spec.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/e2e/tests/full-happy-path.spec.ts)
- **`tests/`** – Unit and integration tests for various packages, including [`tests/workbench/workspace-tree.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/workspace-tree.test.ts)
- **`docs/`** – Docusaurus-based documentation site, deliberately excluded from the workspace lockfile via [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml)
- **`scripts/`** – CI/CD helper scripts and local tooling automation like [`scripts/build.sh`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/build.sh)
- **`public/`** – Static assets including `public/logo-horizontal.png` used by the web UI
- **Root configuration files** – Global TypeScript ([`tsconfig.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tsconfig.json)), ESLint, Prettier, and [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) settings

## The packages/ Directory and @openmaic Scope

The `packages/` directory contains the core business logic of OpenMAIC, organized as individually versioned npm packages. According to the repository source code, these are structured under `packages/@openmaic/*` and published to the npm registry under the `@openmaic` organization scope.

### Core AI Agent Logic (@openmaic/agent)

Located at `packages/@openmaic/agent`, this package contains the fundamental AI agent orchestration logic. It defines the runtime environment for agent execution and exposes the primary `Agent` class that other applications import to instantiate intelligent workflows.

### Plugin Skill Framework (@openmaic/skill)

The `packages/@openmaic/skill` directory implements the extensible skill system that allows third-party capabilities to be registered dynamically. This framework enables the modular architecture where specific AI capabilities can be added or removed without modifying core agent code.

### Shared UI Components (@openmaic/ui)

Found at `packages/@openmaic/ui`, this library provides theme-aware React components used consistently across the platform. The package exports `ThemeProvider` and other design system elements that ensure visual consistency between the main web application and any embedded widget contexts.

## Configuration and Workspace Wiring

The monorepo structure of OpenMAIC relies on specific configuration files to resolve internal dependencies and manage build pipelines.

**[`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml)** defines the workspace boundaries, instructing pnpm to treat all directories under `packages/*` and `packages/@openmaic/*` as distinct packages. The configuration explicitly excludes the documentation site using the `"!packages/docs"` pattern to prevent dependency conflicts between the Docusaurus build and the main application toolchain.

Each package within `packages/@openmaic/*` maintains its own [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) with defined entry points, enabling independent versioning while allowing the `apps/web` application to consume them via workspace protocol references.

## How Imports Work Across the Workspace

The pnpm workspace configuration automatically resolves internal package imports, allowing the Next.js application to import scoped packages as if they were installed from npm. This enables clean code sharing without relative path traversal.

```typescript
// Inside apps/web/pages/index.tsx
import { Agent } from '@openmaic/agent'
import { ThemeProvider } from '@openmaic/ui'

export default function Home() {
  return (
    <ThemeProvider theme={theme}>
      <Agent />
    </ThemeProvider>
  )
}

```

The import paths resolve to their respective `src/` directories within `packages/@openmaic/agent` and `packages/@openmaic/ui` during development, while production builds use the compiled output defined in each package's [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) main entry field.

## Summary

- **OpenMAIC organizes code into `apps/` for applications and `packages/@openmaic/*` for publishable libraries**, enabling clear separation between the Next.js frontend and reusable AI agent modules.
- **[`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) controls the monorepo boundaries**, explicitly excluding the `docs/` directory to isolate documentation build dependencies.
- **Scoped packages follow npm publishing standards**, with each package in `packages/@openmaic/` containing independent [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) files, source directories, and test suites.
- **Global configuration lives in `configs/` and root-level files**, providing shared TypeScript, ESLint, and theme settings consumed by both applications and libraries.
- **Relative imports from `components/` coexist with workspace imports**, allowing non-published UI components to reside outside the packages directory while still being available to the web application.

## Frequently Asked Questions

### What package manager does OpenMAIC use?

OpenMAIC uses **pnpm** as its package manager and workspace orchestrator. The repository relies on [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) to define which directories contain workspace packages, enabling efficient hoisting of shared dependencies and atomic installation across the entire monorepo structure.

### Where are the publishable libraries located?

All publishable libraries reside in the `packages/` directory, specifically under `packages/@openmaic/`. This includes `packages/@openmaic/agent` for core AI logic, `packages/@openmaic/skill` for the plugin framework, and `packages/@openmaic/ui` for shared React components. Each contains its own [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) and is published to npm under the `@openmaic` scope.

### Why is the docs directory excluded from the workspace?

The `docs/` directory is excluded via the `"!packages/docs"` pattern in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) because it runs a separate Docusaurus build toolchain that may have conflicting dependency requirements with the main Next.js application. This isolation prevents version conflicts between the documentation site's React dependencies and the primary application runtime.

### How does the web application consume shared components?

The web application in `apps/web/` consumes shared components through two mechanisms: **workspace imports** for published packages like `@openmaic/ui` using standard npm import syntax, and **relative path imports** for components in the top-level `components/` directory that are not published as standalone packages. Both methods resolve automatically through the pnpm workspace configuration and TypeScript path mapping defined in [`tsconfig.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tsconfig.json).