# makeplane/plane Project Structure: A Complete Guide to the Monorepo Architecture

> Explore the makeplane/plane project structure. Discover how this pnpm monorepo organizes services in apps/ and libraries in packages/ for efficient development. Learn about its workspace setup.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: architecture
- Published: 2026-08-25

---

**The makeplane/plane repository is a pnpm-based monorepo that organizes runnable services under `apps/` and shared libraries under `packages/`, bound together by a workspace definition in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml).**

This open-source project management platform separates deployment targets from reusable code through a clean dual-directory layout. Understanding this structure is essential for contributing to Plane or deploying custom instances, as it dictates how dependencies resolve, builds execute, and services communicate.

## Workspace Configuration and Root Layout

At the repository root, [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) defines the monorepo boundaries and dependency catalog. This file instructs pnpm to treat specific directories as workspace members while excluding legacy services from the Node.js toolchain.

```yaml

# pnpm-workspace.yaml

packages:
  - apps/*
  - packages/*
  - "!apps/api"
  - "!apps/proxy"

```

The `apps/*` pattern includes every deployable service, while `packages/*` captures shared TypeScript libraries. The exclusion entries (`!apps/api` and `!apps/proxy`) are critical architectural decisions: these services are pure Python/Django projects that operate outside the Node.js dependency graph, preventing tooling conflicts while keeping code colocated.

## Top-Level Directory Organization

The repository root contains four primary organizational zones that separate runtime concerns from development infrastructure.

- **`apps/`** – Contains all deployable services, including the React front-end (`web/`), admin console (`admin/`), document export engine (`live/`), and Python REST API (`api/`).
- **`packages/`** – Houses reusable TypeScript modules consumed via `workspace:*` specifiers, including UI components (`ui/`), utilities (`utils/`), and type definitions (`types/`).
- **`docs/`** – Hosts documentation assets such as linting guides and architectural decision records.
- **Docker Compose Files** – [`docker-compose.yml`](https://github.com/makeplane/plane/blob/main/docker-compose.yml) and [`docker-compose-test.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-test.yml) orchestrate the Postgres database, Redis cache, Python API, and Node.js apps for local development.

## Applications in the apps/ Directory

Each entry in `apps/` represents an independently deployable service with its own [`package.json`](https://github.com/makeplane/plane/blob/main/package.json), build pipeline, and runtime requirements.

### web – Primary User Interface

Located at `apps/web/`, this React application serves as the main project management interface. Its [`package.json`](https://github.com/makeplane/plane/blob/main/package.json) defines standard scripts: `dev` for Vite-powered hot reloading, `build` for production bundling, and `check:lint`/`check:types` for quality gates. The app consumes shared workspace packages using imports such as `import { Button } from '@plane/ui'`.

### admin – Administrative Console

The `apps/admin/` directory contains the instance administration UI, sharing identical tooling and scripts with the `web` app. It leverages `@plane/hooks` for authentication logic and `@plane/services` for API communication.

### live – Document Export Service

Housed in `apps/live/`, this Node.js service handles server-side PDF and RTF generation. Unlike the browser-targeted apps, this service runs as a backend process but still participates in the workspace dependency graph, importing shared utilities from `@plane/utils`.

### api – Python Django Backend

The `apps/api/` directory breaks from the Node.js pattern, containing a Django REST framework application. Because Python dependencies are managed separately, this folder is excluded from the pnpm workspace. The API exposes endpoints defined in files such as [`apps/api/plane/web/views.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/web/views.py), which the React front-ends access over HTTP.

## Shared Libraries in the packages/ Directory

The `packages/` directory implements the "build once, use everywhere" philosophy through granular, single-responsibility modules. Each package is a standard npm module that resolves locally via the `workspace:*` specifier.

**`@plane/ui`** – The component library located at `packages/ui/` provides Tailwind-styled React components and Storybook documentation. Source files live in `packages/ui/src/` and export design-system primitives like buttons, avatars, and form inputs.

**`@plane/types`** – Centralized TypeScript definitions stored in `packages/types/` ensure API contract consistency. Front-end apps and utility functions import interfaces such as `Issue` or `IWorkspace` here, creating type safety across the JavaScript/Python boundary.

**`@plane/utils`** – Generic helper functions for URL manipulation, string validation, and data transformation reside in `packages/utils/`. For example, [`packages/utils/src/workspace.ts`](https://github.com/makeplane/plane/blob/main/packages/utils/src/workspace.ts) exports `orderWorkspacesList`, a utility used by both `web` and `admin` apps.

**`@plane/shared-state`** – MobX stores for global state management live here, synchronizing complex UI state (current workspace, selected views) across the `web` and `admin` applications without prop drilling.

**`@plane/i18n`** – Internationalization utilities built on `i18next` provide translation infrastructure that both front-end apps consume through `react-i18next`.

## Build Orchestration and Development Tooling

The monorepo employs a unified toolchain orchestrated by Turbo and pnpm catalogs to ensure consistent builds across disparate services.

**Vite** drives all front-end builds via [`vite.config.ts`](https://github.com/makeplane/plane/blob/main/vite.config.ts) files in each JavaScript app, offering fast HMR and optimized production bundles.

**OxLint and OxFmt** enforce code quality project-wide through scripts defined in each [`package.json`](https://github.com/makeplane/plane/blob/main/package.json): `check:lint` validates code, while `fix:lint` applies automatic corrections.

**Turbo** coordinates the build graph via [`turbo.json`](https://github.com/makeplane/plane/blob/main/turbo.json), enabling parallel execution and aggressive caching of `packages/` builds when their source hasn't changed.

**Docker** provides the integration layer for polyglot services. The root [`docker-compose.yml`](https://github.com/makeplane/plane/blob/main/docker-compose.yml) spins up the Python API, Postgres, Redis, and the Node.js apps simultaneously, ensuring the `web` app can communicate with `apps/api` during local development.

## Cross-Cutting Integration Patterns

Understanding how these structural elements interact reveals the architectural integrity of the system.

**Workspace Resolution** – When [`apps/web/src/components/IssueCard.tsx`](https://github.com/makeplane/plane/blob/main/apps/web/src/components/IssueCard.tsx) imports `import { Avatar } from '@plane/ui'`, pnpm resolves this to the local file system at `packages/ui/src/`, enabling zero-config cross-package development.

**Type Consistency** – All TypeScript apps import domain models from `@plane/types`, guaranteeing that the shape of a "Workspace" or "Issue" in the React code matches the Django serializer definitions in [`apps/api/plane/web/views.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/web/views.py).

**State Synchronization** – The `@plane/shared-state` MobX stores persist user session data and UI preferences in memory, allowing seamless state sharing between the main app and admin console without complex message passing.

## Summary

- The makeplane/plane repository uses a **pnpm workspace** defined in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) to link `apps/*` and `packages/*` into a single dependency graph.
- Runnable services live in **`apps/`**, including the React `web` UI, `admin` console, `live` export service, and the Python Django `api`.
- Shared code resides in **`packages/`**, exposing scoped modules like `@plane/ui`, `@plane/types`, and `@plane/utils` to any app via `workspace:*` imports.
- The Python API is explicitly **excluded** from the Node workspace, preventing tooling conflicts while maintaining monorepo colocation.
- **Turbo**, **Vite**, and **Docker Compose** coordinate builds and local development across the polyglot stack.

## Frequently Asked Questions

### Why does Plane use a monorepo instead of separate repositories?

The monorepo structure ensures that changes to shared type definitions in `packages/types/` immediately propagate to both the `web` and `admin` apps, preventing API contract mismatches. It also centralizes tooling configuration—updates to OxLint or Vite versions apply project-wide through the [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) catalog, reducing maintenance overhead across the codebase.

### How does the Python API coexist with the Node.js applications?

The `apps/api/` directory contains a standard Django project that operates outside the pnpm workspace, as specified by the `!apps/api` exclusion in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml). This isolation allows the Python environment to manage its own dependencies via [`requirements.txt`](https://github.com/makeplane/plane/blob/main/requirements.txt) while remaining colocated for Docker Compose orchestration and version control simplicity.

### What is the purpose of the packages/ directory?

The `packages/` directory contains **reusable libraries** that enforce design consistency and reduce duplication. For example, `@plane/ui` centralizes Tailwind component styling, while `@plane/utils` houses cross-cutting logic like URL builders. Any app can import these using `workspace:*` specifiers, ensuring a single source of truth for utilities without publishing to npm registries.

### How do I add a new shared package to the workspace?

Create a directory under `packages/` with a valid [`package.json`](https://github.com/makeplane/plane/blob/main/package.json) that includes `"name": "@plane/your-package"`. Configure the `main` and `types` entry points to point to your `src/` directory. Other apps can then import it immediately using `import { something } from '@plane/your-package'` without additional linking steps, thanks to the `apps/*` and `packages/*` glob patterns in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml).