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

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 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
• 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 file exports the main navigation header, while 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 – Core data structure for the workspace tree
• lib/workbench/use-workspace-pane-navigation.ts – Hook for pane navigation logic
• 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 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.

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 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 defines workspace-wide scripts, while 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	Declares workspace package locations (packages/*)
package.json (root)	Central scripts, workspace metadata, and dependency management
tsconfig.json	TypeScript compiler settings for path mapping and strict mode
components/header.tsx	Main UI header component rendered across all pages
lib/workbench/workspace-tree.ts	Core workspace data structure and tree manipulation logic
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	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 to reference code across directories:

// 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:

pnpm install
pnpm -r build

The pnpm-workspace.yaml configuration enables these cross-package imports:

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 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 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 with a name scoped to @openmaic/. The 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.

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