Role of the Backend Directory in makeplane/plane: Django API Architecture

TLDR: The backend directory in makeplane/plane is located at apps/api and serves as the Django-based API server that handles data persistence, business logic, authentication, and background task processing for the Plane project management platform.

The makeplane/plane repository organizes its server-side components within the apps/api package rather than a traditional top-level backend folder. This Django application, built as the plane-backend Docker image, exposes REST endpoints for workspace management, issue tracking, and cycle planning while handling asynchronous operations through Celery workers. Understanding the role of the backend directory is essential for contributors integrating with Plane's data layer or deploying self-hosted instances.

Backend Location and Container Build

Although there is no folder literally named backend at the repository root, the backend codebase resides entirely within apps/api. According to the repository structure and CONTRIBUTING.md, this package contains all server-side logic, distinguishing it from the Next.js frontend in apps/web and the collaborative spaces in apps/space.

The containerization logic in apps/api/Dockerfile.dev defines how the plane-backend image is constructed. This image is later referenced in production deployment configurations within the deployments/ directory. The Django application entry point is apps/api/plane/wsgi.py, which initializes the WSGI server for production traffic.

Core Responsibilities

The apps/api directory functions as the central nervous system of Plane, implementing everything from database schemas to API rate limiting.

Data Models and ORM

Core business entities live in apps/api/plane/db/models/, where Django ORM classes define workspaces, projects, issues, cycles, and user relationships. These models enforce data integrity and provide the abstraction layer for PostgreSQL interactions, ensuring consistent data validation across the application.

REST API Endpoints

The backend exposes CRUD operations through viewsets located in apps/api/plane/app/views/ and apps/api/plane/api/views/. For example, workspace creation requests route to apps/api/plane/app/views/workspace.py via the WorkspaceViewSet.create() method, while issue queries are handled by IssueViewSet in apps/api/plane/app/views/issue/base.py using ComplexFilterBackend for advanced filtering.

Authentication and Permissions

Security logic resides in apps/api/plane/authentication/, managing JWT token generation, session validation, and permission checks. This ensures that API requests to sensitive project data are properly authorized before reaching business logic layers, protecting workspace isolation and project confidentiality.

Background Task Processing

Asynchronous operations such as email delivery, CSV exports, and analytics processing are handled by Celery workers. Task definitions are stored in apps/api/plane/bg_tasks/, with specific export logic implemented in apps/api/plane/bg_tasks/export.py. These workers process jobs outside the request-response cycle to maintain API responsiveness during resource-intensive operations.

Storage and Caching Configuration

File uploads and static assets are managed through Django-Storages, with configuration in apps/api/plane/settings/storage.py supporting S3 or local filesystem backends. Performance optimization relies on Redis-based caching implemented in apps/api/plane/utils/cache.py, which also handles API rate limiting to prevent abuse.

OpenAPI Documentation

The backend auto-generates API specifications using utilities in apps/api/plane/utils/openapi/, ensuring that frontend developers and third-party integrators have up-to-date schema documentation derived directly from the viewsets.

Key Configuration Files

Several critical files define how the Django application initializes and routes requests:

• apps/api/plane/wsgi.py: WSGI entry point for production servers.
• apps/api/plane/settings/common.py: Centralized settings for databases, middleware, and installed applications.
• apps/api/plane/urls.py: Root URL configuration that aggregates all API routers and viewset endpoints.

API Usage Examples

The backend accepts standard HTTP requests with Bearer token authentication. Below are typical interactions demonstrating the API surface:

Create a workspace:

curl -X POST https://api.plane.so/api/v1/workspaces/ \
     -H "Authorization: Bearer <your-access-token>" \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Corp","slug":"acme"}'

List project issues:

curl -H "Authorization: Bearer <token>" \
     https://api.plane.so/api/v1/projects/<project_id>/issues/

Trigger asynchronous export:

curl -X POST -H "Authorization: Bearer <token>" \
     https://api.plane.so/api/v1/projects/<project_id>/exports/ \
     -d '{"type":"csv"}'

Summary

• The makeplane/plane backend is not at the root but located in apps/api, packaged as the plane-backend Docker image.
• It is a Django application using the Django ORM in apps/api/plane/db/models/ for data persistence.
• REST APIs are implemented in apps/api/plane/app/views/ with authentication handled in apps/api/plane/authentication/.
• Celery workers in apps/api/plane/bg_tasks/ process asynchronous tasks like exports and emails.
• Redis caching and rate limiting are configured in apps/api/plane/utils/cache.py.
• Entry points include apps/api/plane/wsgi.py and apps/api/plane/urls.py.

Frequently Asked Questions

Where is the backend directory located in makeplane/plane?

There is no top-level folder named backend. Instead, the backend code resides in apps/api as documented in the project's CONTRIBUTING.md. This structure keeps all applications within the apps/ directory alongside the frontend (apps/web) and space (apps/space) packages.

What framework powers the Plane backend?

The backend is built on Django using the Django REST Framework. It uses standard Django ORM for database operations, Django-Storages for file management, and integrates Celery for asynchronous task processing. The WSGI entry point at apps/api/plane/wsgi.py initializes this stack.

How does the backend handle background tasks?

Long-running operations are offloaded to Celery workers. Task definitions are stored in apps/api/plane/bg_tasks/, with specific implementations like export jobs located in apps/api/plane/bg_tasks/export.py. These tasks run outside the main request cycle to prevent API timeouts during intensive operations like data exports or bulk email sends.

What Docker image name is used for the Plane backend?

The backend is built into an image named plane-backend using apps/api/Dockerfile.dev. This image is referenced in the Docker Compose files within deployments/cli/community/docker-compose.yml to orchestrate the full Plane stack including PostgreSQL, Redis, and the frontend applications.

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