# OpenMAIC Monorepo Directory Structure: A Complete Guide to the Codebase Organization

> Explore the OpenMAIC monorepo directory structure. Understand the organization of packages components lib configs scripts tests assets and documentation for efficient development and independent publishing.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-10

---

**The OpenMAIC monorepo is organized as a pnpm workspace with eight top-level directories—`packages/`, `components/`, `lib/`, `configs/`, `scripts/`, `tests/`, `assets/`, and documentation—enabling coordinated builds and independent package publishing.**

The THU-MAIC/OpenMAIC repository follows a classic JavaScript/TypeScript monorepo pattern managed by pnpm workspaces. Understanding the directory structure of the OpenMAIC monorepo is essential for contributing to the workspace UI, extending the PPTX generation libraries, or modifying the documentation site.

## Top-Level Directory Layout

The root of the repository separates concerns into distinct folders, each serving a specific architectural purpose. The workspace configuration lives in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) at the repository root, which enumerates all publishable packages under the `packages/*` glob pattern.

### packages/

The `packages/` directory contains independent, publishable npm packages that version and release together. Key packages include:

- **`packages/pptxgenjs/`** – The PPTX generation library entry point at [`src/pptxgen.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/pptxgen.ts)
- **`packages/mathml2omml/`** – MathML to Office Math Markup conversion utilities
- **`packages/docs/`** – The Next.js documentation site built with MDX, sourcing content from `packages/docs/content/docs/`

### components/

Shared React components used across the web UI live here. The [`components/header.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/header.tsx) file exports the main navigation header, while [`components/workbench/workspace-shell.css`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/workbench/workspace-shell.css) provides styling for the workspace container. These components import utilities from `lib/` to manage state and navigation.

### lib/

Core library code implementing business logic resides in `lib/`. The `lib/workbench/` subdirectory contains the interactive workspace implementation:

- [`lib/workbench/workspace-tree.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-tree.ts) – Core data structure for the workspace tree
- [`lib/workbench/use-workspace-pane-navigation.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/use-workspace-pane-navigation.ts) – Hook for pane navigation logic
- [`lib/import/use-import-pptx.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/import/use-import-pptx.ts) – Helper for importing PPTX files into the workspace

### configs/

Centralized static configuration files define global behavior. The [`configs/theme.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/configs/theme.ts) file exports UI theming constants, while adjacent files define hot-key mappings and MIME type registrations. Individual packages import these configurations to maintain consistency across the monorepo.

### scripts/

Build-time and CI helper scripts automate repetitive tasks. The `scripts/openmaic-packages.mjs` module provides utilities for packaging and publishing workflows, referenced by GitHub Actions pipelines in [`.github/workflows/ci.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/.github/workflows/ci.yml).

### tests/

End-to-end and unit test suites use Vitest for unit tests and Playwright for browser automation. Test files mirror the source structure; for example, [`tests/workbench/workspace-tree.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/workspace-tree.test.ts) validates the workspace tree logic implemented in `lib/`.

### assets/

Static media including `assets/logo-horizontal.png` and other GIFs or PNGs support both the UI and documentation site.

## How the Architecture Fits Together

The directory structure of the OpenMAIC monorepo creates clear boundaries between UI components, business logic, and publishable libraries.

**Workspace Core** – The `lib/workbench/*` modules implement the interactive "workspace" UI featuring panes, rails, navigation, and session memory. These utilities are consumed by React components in `components/` and by the documentation site package.

**Package Coordination** – The root [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) defines workspace-wide scripts, while [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) enables version-coordinated builds. Running `pnpm -r build` compiles all packages in dependency order.

**Configuration Flow** – Global UI and system behavior originate in `configs/`. The theme configuration imported by `components/` ensures visual consistency, while build scripts in `scripts/` enforce standardized packaging rules.

**Documentation Integration** – The `packages/docs` Next.js application imports shared UI components from `components/` to render MDX content located in `packages/docs/content/docs/`, creating a unified documentation experience that tests the same components used in production.

## Key Files and Entry Points

These critical files provide entry points for navigating and extending the codebase:

| File | Role |
|------|------|
| [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) | Declares workspace package locations (`packages/*`) |
| [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) (root) | Central scripts, workspace metadata, and dependency management |
| [`tsconfig.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tsconfig.json) | TypeScript compiler settings for path mapping and strict mode |
| [`components/header.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/header.tsx) | Main UI header component rendered across all pages |
| [`lib/workbench/workspace-tree.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-tree.ts) | Core workspace data structure and tree manipulation logic |
| [`packages/pptxgenjs/src/pptxgen.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/pptxgenjs/src/pptxgen.ts) | PPTX generation library public API |
| `packages/docs/next.config.mjs` | Next.js configuration for the documentation site |
| [`.github/workflows/ci.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/.github/workflows/ci.yml) | Continuous integration pipeline for testing, linting, and building |
| `scripts/openmaic-packages.mjs` | Helper script for package versioning and publishing |

## Navigating the Codebase

Import paths use TypeScript path aliases defined in [`tsconfig.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tsconfig.json) to reference code across directories:

```typescript
// Import a shared UI component
import { Header } from '@/components/header';

// Use workspace utilities
import { useWorkspacePaneNavigation } from '@/lib/workbench/use-workspace-pane-navigation';

// Consume a published package
import PPTXGenJS from '@openmaic/pptxgenjs';

```

Build the entire monorepo from the root directory:

```bash
pnpm install
pnpm -r build

```

The [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) configuration enables these cross-package imports:

```yaml
packages:
  - 'packages/*'
linkWorkspacePackages: true
publicHoistPattern:
  - '*'

```

## Summary

The directory structure of the OpenMAIC monorepo organizes code into eight logical top-level folders managed by pnpm workspaces:

- **`packages/`** contains versioned, publishable libraries including the PPTX generator and documentation site
- **`components/`** houses shared React UI components consumed by the main application and docs
- **`lib/`** implements core workspace logic including tree structures and import handlers
- **`configs/`** centralizes theming, hot-keys, and system constants
- **`scripts/`** and **`.github/workflows/`** automate CI/CD and publishing tasks
- **`tests/`** mirrors the source structure for Vitest and Playwright validation
- **`assets/`** stores static media for the UI and documentation

## Frequently Asked Questions

### What package manager does OpenMAIC use for its monorepo?

OpenMAIC uses **pnpm workspaces** defined in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) at the repository root. The configuration includes all directories under `packages/*` as workspace members, enabling efficient dependency hoisting and coordinated versioning across the `@openmaic` scope.

### Where are the React UI components located in OpenMAIC?

Shared React components reside in the **`components/`** directory at the repository root. Files like [`components/header.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/header.tsx) export reusable UI elements, while `components/workbench/` contains workspace-specific shells and navigation components that import logic from `lib/workbench/`.

### How are the packages in the OpenMAIC monorepo defined?

Packages are defined as subdirectories under **`packages/`**, each containing its own [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) with a name scoped to `@openmaic/`. The [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) file enumerates these packages with the glob pattern `packages/*`, allowing the build system to treat them as workspace dependencies while maintaining independent versioning.

### Where is the documentation site source code stored?

The documentation site is implemented as a workspace package in **`packages/docs/`**. It uses Next.js with MDX rendering, sourcing content from `packages/docs/content/docs/` and importing shared React components from the root `components/` directory to ensure the documentation UI matches the main application.