What Are the Different Modules and Applications Within Plane? A Complete Architecture Guide

Plane is organized as a pnpm monorepo containing distinct runnable applications in apps/ and shared libraries in packages/, collectively delivering a unified project management platform.

The open-source Plane repository (makeplane/plane) follows a modular monorepo architecture that separates concerns into independently deployable services and reusable frontend packages. Understanding these different modules or applications within Plane is essential for developers contributing to the codebase or self-hosting the platform.

Core Applications in the apps/ Directory

The apps/ directory contains the primary executable services that power Plane’s runtime environment. Each application maintains its own package.json and build configuration.

Web Application (apps/web)

The Web module is the primary client-side React application that users interact with directly. Built with Vite, it serves as the main dashboard for project management, issue tracking, and collaboration. The entry point configuration is located at apps/web/package.json, which defines the dependencies and scripts for the main UI.

Space Application (apps/space)

Space provides a lightweight, sandboxed UI designed for embedding Plane components—specifically the "Space" iframe widget used for external integrations. This isolated environment ensures that embedded views run securely without exposing the full application surface. Configuration resides in apps/space/package.json.

Proxy Service (apps/proxy)

The Proxy module acts as a reverse-proxy service based on Caddy, designed to front other services in self-hosted deployments. It handles routing, SSL termination, and load balancing between the frontend applications and backend APIs. The container specification is defined in apps/proxy/Dockerfile.ce.

Live Server (apps/live)

Live is a minimal Node.js server that powers real-time collaboration features via WebSocket connections and Server-Sent Events (SSE). This service enables live updates when multiple users edit issues or cycles simultaneously. The server initialization logic is found in apps/live/src/start.ts.

Django API (apps/api)

While residing outside the Node.js monorepo structure in the preview branch, the API module represents the core Django backend that stores work items, cycles, modules, and user data. It exposes a REST API consumed by the frontend services through the packages/services wrappers.

Shared Packages in the packages/ Directory

The packages/ directory contains reusable libraries that enforce consistency across applications. These are published as internal packages (e.g., @plane/ui, @plane/services) and imported by the apps above.

State Management (packages/shared-state)

Centralized state logic lives in the shared-state package, which implements MobX stores for workspaces, filters, and selections. These stores are injected via React context providers throughout the UI. The workspace-specific implementation is located at packages/shared-state/src/store/workspace.store.ts.

UI Components (packages/ui)

The UI package provides a design system of reusable React primitives—including buttons, icons, and layout components—ensuring visual consistency across the Web and Space applications.

API Services (packages/services)

The services package contains thin TypeScript wrappers around the Django REST API. These handle authentication, pagination, and caching for entities like workspaces, users, issues, and cycles. Key files include packages/services/src/workspace/workspace.service.ts and packages/services/src/intake/issue.service.ts.

Rich Text Editor (packages/editor)

The editor package implements the block-based rich text editor used throughout Plane, supporting drag-and-drop functionality, tables, and markdown serialization. The core library entry point is packages/editor/src/lib.ts.

Utility Libraries

Several specialized packages handle cross-cutting concerns:

• packages/utils – Shared helper utilities for workspace handling and filter logic (packages/utils/src/workspace.ts).
• packages/hooks – Custom React hooks including useLocalStorage and useOutsideClickDetector (packages/hooks/src/use-local-storage.tsx).
• packages/constants – Centralized enums and hard-coded values for themes, view types, and SSWR settings (packages/constants/src/views.ts).
• packages/decorators – TypeScript decorators that transform class methods into HTTP endpoints for REST and WebSocket routes (packages/decorators/src/rest.ts).
• packages/logger – Request-logging middleware used by Node-side services (packages/logger/src/middleware.ts).
• packages/i18n – Translation files and internationalization helpers.
• packages/tailwind-config – Shared Tailwind CSS configuration and design tokens (packages/tailwind-config/variables.css).
• packages/codemods – Automated code transformation scripts for refactoring (packages/codemods/tests/remove-directives.spec.ts).

How the Modules Work Together

The architecture follows a clear dependency graph:

1. Frontend apps (web, space) consume shared packages (ui, hooks, editor) and state stores (shared-state).
2. State management uses MobX in packages/shared-state, with stores hydrating from the API services layer.
3. API integration flows through packages/services, which wraps the Django backend (external to the Node monorepo).
4. Real-time updates are brokered through the apps/live WebSocket server, broadcasting to connected clients.
5. Cross-cutting concerns like logging (packages/logger) and styling (packages/tailwind-config) are imported uniformly across all applications.

Implementation Examples

Accessing Workspace State

Components import stores from the shared-state package to access centralized data:

import { useWorkspaceStore } from '@plane/shared-state';

export function WorkspaceHeader() {
  const { currentWorkspace } = useWorkspaceStore();
  return <h1>{currentWorkspace?.name ?? 'Untitled Workspace'}</h1>;
}

Source: packages/shared-state/src/store/workspace.store.ts

Fetching Issues via Service Layer

The services package abstracts API calls into typed methods:

import { IssueService } from '@plane/services';

async function loadOpenIssues(projectId: string) {
  const issues = await IssueService.getIssues({
    projectId,
    filters: { state: 'open' },
  });
  return issues;
}

Source: packages/services/src/intake/issue.service.ts

Using Shared Hooks

Custom hooks from the hooks package manage browser APIs:

import { useLocalStorage } from '@plane/hooks';

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage<string>('plane-theme', 'light');
  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Switch to {theme === 'light' ? 'dark' : 'light'} mode
    </button>
  );
}

Source: packages/hooks/src/use-local-storage.tsx

Summary

• Plane is a pnpm monorepo divided into runnable apps/ and library packages/.
• The four main applications are Web (primary UI), Space (embedded widget), Proxy (reverse proxy), and Live (real-time server).
• The API backend is Django-based and pairs with the Node.js frontend via the services package.
• Shared-state manages MobX stores, while services wraps REST endpoints with TypeScript.
• Editor, UI, and hooks packages provide reusable frontend primitives.
• Decorators, constants, and logger packages handle infrastructure and cross-cutting concerns.

Frequently Asked Questions

What is the difference between the Web and Space applications in Plane?

The Web application (apps/web) is the full-featured React dashboard where users manage projects, cycles, and issues. The Space application (apps/space) is a lightweight, sandboxed environment designed specifically for embedding Plane components in external sites via iframe, providing isolated, secure access to specific views without loading the entire application.

How does state management work across different modules in Plane?

State is centralized in packages/shared-state using MobX stores that define observable data models for workspaces, projects, and filters. These stores are instantiated at the application root and injected into components via React context. The apps/web and apps/space applications both consume these same stores, ensuring consistent state across the user interface.

What is the purpose of the Live application in Plane?

The Live application (apps/live) is a dedicated Node.js server that handles WebSocket connections and Server-Sent Events. It enables real-time collaboration features—such as live cursor updates and simultaneous issue editing—by broadcasting state changes to all connected clients without requiring the main Django API to maintain persistent WebSocket connections.

How does the Proxy application fit into a self-hosted Plane deployment?

The Proxy module (apps/proxy) serves as a Caddy-based reverse proxy that sits in front of the Web, Space, and API services in self-hosted environments. Defined in apps/proxy/Dockerfile.ce, it handles SSL termination, request routing, and load balancing, simplifying the networking configuration required to run Plane on private infrastructure.

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