# humansignal/label-studio architecture

> Architecture diagram of the GitHub repository humansignal/label-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/humansignal/label-studio
- Repository: https://github.com/humansignal/label-studio

## Overview

1. **What the repo is**
   - This is the full Label Studio product monorepo: a Python backend plus a large React/TypeScript frontend platform, documentation site, test harnesses, and deployment assets.
   - The architecture is centered on a Django web application that serves APIs and HTML entrypoints, while the frontend bundles the labeling UI and data management UI.

2. **Backend runtime and server boundary**
   - The backend lives under `label_studio/` and runs as a Django app (`manage.py`, `core/wsgi.py`, `server.py`).
   - It is deployed in several modes: local dev, Docker, Docker Compose, cloud-specific images, and production stacks with Nginx in front.
   - Persistent state is primarily in a relational database, with SQLite for quick local use and PostgreSQL for production; Redis is used for activity/session/state-related features.

3. **Core backend layer**
   - `label_studio/core/` provides shared backend infrastructure: settings, URL routing, middleware, permissions, storage helpers, request context, feature flags, migrations, logging/sentry, and static file serving.
   - This is the glue layer that all other backend apps depend on, and it defines the top-level request/response and configuration boundaries.

4. **Domain apps and their responsibilities**
   - The backend is split into Django apps by domain: `projects`, `tasks`, `data_manager`, `data_import`, `data_export`, `organizations`, `users`, `webhooks`, `session_policy`, `jwt_auth`, `ml`, `ml_models`, `ml_model_providers`, `labels_manager`, and `io_storages`.
   - Each domain owns its models, serializers, API routes, and migrations, which keeps business logic separated by concern rather than by transport layer.

5. **Main labeling data flow**
   - The central flow is: create a project → define labeling config/template → import tasks/data → annotate tasks → store annotations/predictions → export results.
   - `projects` owns project configuration and lifecycle, `tasks` owns task/annotation/prediction records, and `data_manager` exposes task browsing/filtering/action workflows.
   - This is the core application loop that the annotation UI drives through backend APIs.

6. **State and workflow engine**
   - `fsm/` is a dedicated subsystem for finite-state management of project, task, and annotation lifecycle.
   - It contains transition definitions, registry/state inference, serializers, and workflow executors, indicating that state changes are treated as explicit business processes rather than ad hoc model updates.
   - This matters for diagrams because state transitions are a separate boundary that sits between API actions and persistence.

7. **Import/export and storage integration**
   - `data_import`, `data_export`, and `io_storages` handle file ingestion, exporting, and external storage connectors.
   - Storage backends include local files, S3, GCS, Azure Blob, Redis, and Databricks-oriented paths; there are also presign/proxy APIs for serving remote data securely.
   - In the deployment topology, Nginx often serves as the static/media proxy, while the app coordinates permissions and metadata for these stores.

8. **Machine learning integration boundary**
   - `ml/`, `ml_models/`, `ml_model_providers/`, and `labels_manager/` model integration with external ML backends and model providers.
   - The system supports predictions, model runs, provider connections, and active-learning-style workflows where models pre-label tasks and annotations feed back into the labeling process.
   - The external ML backend is not embedded; Label Studio treats it as a connected service.

9. **Authentication, users, and org-level access**
   - `users/`, `organizations/`, `jwt_auth/`, and `session_policy/` implement identity, membership, session limits, and token-based access.
   - The backend also includes middleware and management commands for org/user lifecycle operations, plus support for enterprise auth-related workflows such as SSO/SCIM-related paths visible in docs and routes.
   - For architecture diagrams, this is the authorization boundary around all domain APIs and UI entrypoints.

10. **Webhook and automation layer**
   - `webhooks/` provides outbound event hooks for system events, allowing external systems to react to organization/task/project changes.
   - This is an integration edge, not a core data store: it observes internal events and pushes notifications outward.

11. **Frontend platform structure**
   - The frontend workspace is under `web/` and is organized as an Nx monorepo with multiple apps and shared libraries.
   - The main app is `web/apps/labelstudio`, which contains the user-facing product UI; `web/apps/playground` is a separate sandbox; `web/apps/labelstudio-e2e` contains Cypress end-to-end tests.
   - Shared packages such as `web/libs/editor`, `web/libs/datamanager`, `web/libs/ui`, `web/libs/core`, and `web/libs/app-common` split the UI into reusable layers.

12. **Frontend subsystem boundaries**
   - `web/libs/editor` is the annotation editor engine and is the most domain-specific frontend library; it includes tags, regions, tools, stores, and media-specific behavior.
   - `web/libs/datamanager` powers the data exploration/table/grid experience and task management workflows.
   - `web/libs/ui` and `web/libs/core` provide design-system components, API providers, hooks, and cross-app utilities; these are shared infrastructure, not product logic.

13. **Docs and public-facing content**
   - `docs/` is a separate documentation site with its own build/runtime, Netlify assets, edge functions, and content generators.
   - It is architecturally adjacent to the product rather than part of the runtime path, but it matters because it publishes templates, tutorials, and release documentation that mirror the product’s feature surface.

14. **Testing, CI/CD, and operational tooling**
   - The repo has deep automated coverage: Django tests, Tavern API tests, Pytest, frontend Jest, Cypress, and load tests.
   - `.github/workflows/` and the Dockerfiles/compose files show that the system is built, tested, and packaged as both Python distributions and container images.
   - Operational scripts handle migrations, static assets, entrypoint bootstrapping, and environment-specific deployments.

15. **How to draw the architecture**
   - Draw three main planes: the **backend API and business logic** (Django apps + FSM + storage/ML integrations), the **frontend product shell** (labeling editor + data manager + shared UI libs), and the **external infrastructure** (PostgreSQL/SQLite, Redis, object storage, Nginx, ML backends, auth providers, webhooks).
   - The primary data path is browser UI → Django APIs → database/storage/ML services, with state transitions and webhooks branching off the core transaction flow.

Main entry points: [`label_studio/core`](https://github.com/humansignal/label-studio/tree/develop/label_studio/core) (Core), [`web/apps/labelstudio`](https://github.com/humansignal/label-studio/tree/develop/web/apps/labelstudio) (Label Studio), [`label_studio/tasks`](https://github.com/humansignal/label-studio/tree/develop/label_studio/tasks) (Tasks), [`deploy`](https://github.com/humansignal/label-studio/tree/develop/deploy) (Deploy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_manage["manage.py<br/>Django entry<br/>[manage.py]"]
  node_server["server.py<br/>App server<br/>[server.py]"]
  node_core["Core<br/>Backend glue"]
  node_projects["Projects<br/>Project domain"]
  node_tasks["Tasks<br/>Task domain"]
  node_data_manager["Data manager<br/>Browse workflow"]
  node_fsm["FSM<br/>State engine"]
  node_data_import["Import<br/>Ingest"]
  node_data_export["Export<br/>Egress"]
  node_io_storages["Storages<br/>Storage connectors"]
  node_ml["ML<br/>Model backend"]
  node_ml_models["Model runs<br/>ML ops"]
  node_ml_providers["Providers"]
  node_users["Users<br/>Identity"]
  node_orgs["Organizations<br/>Membership"]
  node_auth["JWT auth<br/>Auth layer"]
  node_sessions["Session policy<br/>Session control"]
  node_webhooks["Webhooks<br/>Outbound events"]
end

subgraph group_frontend["Frontend"]
  node_webapp["Label Studio<br/>Product shell"]
  node_editor["Editor<br/>Annotation engine"]
  node_dm_ui["Data manager UI<br/>Exploration UI"]
  node_core_ui["Core UI<br/>Frontend infra"]
  node_ui["UI kit<br/>Design system"]
end

subgraph group_infra["Infra"]
  node_deploy["Deploy<br/>Runtime packaging"]
  node_ci["CI/CD<br/>Automation<br/>[workflows]"]
  node_runtime[("DB/Redis/ML<br/>External services")]
end

subgraph group_docs["Docs"]
  node_docs_site["Docs site<br/>Documentation"]
end

node_manage -->|"boots"| node_core
node_server -->|"hosts"| node_core
node_core -->|"routes"| node_projects
node_core -->|"routes"| node_tasks
node_core -->|"routes"| node_data_manager
node_core -->|"routes"| node_data_import
node_core -->|"routes"| node_data_export
node_core -->|"routes"| node_io_storages
node_core -->|"routes"| node_ml
node_core -->|"routes"| node_orgs
node_core -->|"routes"| node_users
node_core -->|"protects"| node_auth
node_core -->|"enforces"| node_sessions
node_projects -->|"owns"| node_tasks
node_tasks -->|"transitions"| node_fsm
node_projects -->|"transitions"| node_fsm
node_tasks -->|"feeds"| node_data_manager
node_data_import -->|"creates"| node_tasks
node_data_export -->|"reads"| node_tasks
node_io_storages -->|"stores"| node_runtime
node_ml -->|"calls"| node_runtime
node_ml_models -->|"executes"| node_ml
node_ml_providers -->|"connects"| node_runtime
node_webapp -->|"embeds"| node_editor
node_webapp -->|"embeds"| node_dm_ui
node_webapp -->|"uses"| node_core_ui
node_editor -->|"consumes APIs"| node_core
node_dm_ui -->|"consumes APIs"| node_data_manager
node_docs_site -->|"documents"| node_webapp
node_deploy -->|"packages"| node_core
node_deploy -->|"serves"| node_webapp
node_deploy -->|"depends on"| node_runtime
node_ci -->|"builds"| node_deploy
node_ci -->|"tests"| node_webapp
node_ci -->|"tests"| node_core
node_webhooks -->|"emits"| node_runtime

click node_manage "https://github.com/humansignal/label-studio/blob/develop/label_studio/manage.py"
click node_server "https://github.com/humansignal/label-studio/blob/develop/label_studio/server.py"
click node_core "https://github.com/humansignal/label-studio/tree/develop/label_studio/core"
click node_projects "https://github.com/humansignal/label-studio/tree/develop/label_studio/projects"
click node_tasks "https://github.com/humansignal/label-studio/tree/develop/label_studio/tasks"
click node_data_manager "https://github.com/humansignal/label-studio/tree/develop/label_studio/data_manager"
click node_fsm "https://github.com/humansignal/label-studio/tree/develop/label_studio/fsm"
click node_data_import "https://github.com/humansignal/label-studio/tree/develop/label_studio/data_import"
click node_data_export "https://github.com/humansignal/label-studio/tree/develop/label_studio/data_export"
click node_io_storages "https://github.com/humansignal/label-studio/tree/develop/label_studio/io_storages"
click node_ml "https://github.com/humansignal/label-studio/tree/develop/label_studio/ml"
click node_ml_models "https://github.com/humansignal/label-studio/tree/develop/label_studio/ml_models"
click node_ml_providers "https://github.com/humansignal/label-studio/tree/develop/label_studio/ml_model_providers"
click node_users "https://github.com/humansignal/label-studio/tree/develop/label_studio/users"
click node_orgs "https://github.com/humansignal/label-studio/tree/develop/label_studio/organizations"
click node_auth "https://github.com/humansignal/label-studio/tree/develop/label_studio/jwt_auth"
click node_sessions "https://github.com/humansignal/label-studio/tree/develop/label_studio/session_policy"
click node_webhooks "https://github.com/humansignal/label-studio/tree/develop/label_studio/webhooks"
click node_webapp "https://github.com/humansignal/label-studio/tree/develop/web/apps/labelstudio"
click node_editor "https://github.com/humansignal/label-studio/tree/develop/web/libs/editor"
click node_dm_ui "https://github.com/humansignal/label-studio/tree/develop/web/libs/datamanager"
click node_core_ui "https://github.com/humansignal/label-studio/tree/develop/web/libs/core"
click node_ui "https://github.com/humansignal/label-studio/tree/develop/web/libs/ui"
click node_docs_site "https://github.com/humansignal/label-studio/tree/develop/docs"
click node_deploy "https://github.com/humansignal/label-studio/tree/develop/deploy"
click node_ci "https://github.com/humansignal/label-studio/blob/develop/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manage,node_server,node_core,node_projects,node_tasks,node_data_manager,node_fsm,node_data_import,node_data_export,node_io_storages,node_ml,node_ml_models,node_ml_providers,node_users,node_orgs,node_auth,node_sessions,node_webhooks toneBlue
class node_webapp,node_editor,node_dm_ui,node_core_ui,node_ui toneAmber
class node_deploy,node_ci,node_runtime toneMint
class node_docs_site toneRose
```

## Components

### Backend

Django application, domain apps, workflow engine, and integrations.

- [manage.py](https://github.com/humansignal/label-studio/blob/develop/label_studio/manage.py): Django entry · Command entrypoint for Django management and local server operations. · `label_studio/manage.py`
- [server.py](https://github.com/humansignal/label-studio/blob/develop/label_studio/server.py): App server · Process bootstrap for running the Label Studio application. · `label_studio/server.py`
- [Core](https://github.com/humansignal/label-studio/tree/develop/label_studio/core): Backend glue · Shared backend infrastructure: settings, URLs, middleware, permissions, storage helpers, logging, and static serving. · `label_studio/core`
- [Projects](https://github.com/humansignal/label-studio/tree/develop/label_studio/projects): Project domain · Project lifecycle, labeling config, settings, summaries, and signals. · `label_studio/projects`
- [Tasks](https://github.com/humansignal/label-studio/tree/develop/label_studio/tasks): Task domain · Tasks, annotations, predictions, locks, completion history, and task-level APIs. · `label_studio/tasks`
- [Data manager](https://github.com/humansignal/label-studio/tree/develop/label_studio/data_manager): Browse workflow · Task browsing, filtering, bulk actions, and data management APIs. · `label_studio/data_manager`
- [FSM](https://github.com/humansignal/label-studio/tree/develop/label_studio/fsm): State engine · Explicit finite-state transitions and lifecycle inference for projects, tasks, and annotations. · `label_studio/fsm`
- [Import](https://github.com/humansignal/label-studio/tree/develop/label_studio/data_import): Ingest · Task/data ingestion and upload flows. · `label_studio/data_import`
- [Export](https://github.com/humansignal/label-studio/tree/develop/label_studio/data_export): Egress · Result export and converted-format handling. · `label_studio/data_export`
- [Storages](https://github.com/humansignal/label-studio/tree/develop/label_studio/io_storages): Storage connectors · Local, cloud, and proxy storage integrations for import/export and remote data access. · `label_studio/io_storages`
- [ML](https://github.com/humansignal/label-studio/tree/develop/label_studio/ml): Model backend · External ML backend integration for predictions and model-assisted labeling. · `label_studio/ml`
- [Model runs](https://github.com/humansignal/label-studio/tree/develop/label_studio/ml_models): ML ops · Model runs, versions, and project-linked model execution records. · `label_studio/ml_models`
- [Providers](https://github.com/humansignal/label-studio/tree/develop/label_studio/ml_model_providers): ML providers · Connections to third-party model providers and available model catalogs. · `label_studio/ml_model_providers`
- [Users](https://github.com/humansignal/label-studio/tree/develop/label_studio/users): Identity · User accounts, preferences, hotkeys, and activity-related logic. · `label_studio/users`
- [Organizations](https://github.com/humansignal/label-studio/tree/develop/label_studio/organizations): Membership · Organization membership, admin views, and org-scoped access control. · `label_studio/organizations`
- [JWT auth](https://github.com/humansignal/label-studio/tree/develop/label_studio/jwt_auth): Auth layer · Token-based auth, middleware, and JWT-specific account access. · `label_studio/jwt_auth`
- [Session policy](https://github.com/humansignal/label-studio/tree/develop/label_studio/session_policy): Session control · Session timeout and policy enforcement boundary. · `label_studio/session_policy`
- [Webhooks](https://github.com/humansignal/label-studio/tree/develop/label_studio/webhooks): Outbound events · Event hooks for notifying external systems about internal changes. · `label_studio/webhooks`

### Frontend

React/Nx product UI, shared libraries, and annotation editor.

- [Label Studio](https://github.com/humansignal/label-studio/tree/develop/web/apps/labelstudio): Product shell · Main React application for the product UI and page routing. · `web/apps/labelstudio`
- [Editor](https://github.com/humansignal/label-studio/tree/develop/web/libs/editor): Annotation engine · Core labeling editor with tags, regions, tools, stores, and media-specific interaction models. · `web/libs/editor`
- [Data manager UI](https://github.com/humansignal/label-studio/tree/develop/web/libs/datamanager): Exploration UI · Frontend for task tables, filters, bulk actions, and data browsing workflows. · `web/libs/datamanager`
- [Core UI](https://github.com/humansignal/label-studio/tree/develop/web/libs/core): Frontend infra · Shared frontend hooks, API providers, utilities, and app-common layers. · `web/libs/core`
- [UI kit](https://github.com/humansignal/label-studio/tree/develop/web/libs/ui): Design system · Reusable visual components, tokens, dialogs, and app-wide UI primitives. · `web/libs/ui`

### Infra

Deployment, external services, and runtime dependencies.

- [Deploy](https://github.com/humansignal/label-studio/tree/develop/deploy): Runtime packaging · Dockerfiles, compose stacks, Nginx config, entrypoints, and release scripts. · `deploy`
- [CI/CD](https://github.com/humansignal/label-studio/blob/develop/.github/workflows): Automation · GitHub Actions, build/test pipelines, release automation, and quality gates. · `.github/workflows`
- **DB/Redis/ML**: External services · Primary runtime dependencies: relational database, Redis, object storage, Nginx, auth providers, and external ML services.

### Docs

Public documentation and content generation.

- [Docs site](https://github.com/humansignal/label-studio/tree/develop/docs): Documentation · Separate documentation runtime with guides, templates, tutorials, and Netlify assets. · `docs`

## Connections

- manage.py → Core: boots · Management commands load shared settings and routing.
- server.py → Core: hosts · App process initializes Django through the core configuration boundary.
- Core → Projects: routes · Core URLs and permissions expose the project domain.
- Core → Tasks: routes · Core URLs and permissions expose the task domain.
- Core → Data manager: routes · Core routes task browsing and bulk actions.
- Core → Import: routes · Core exposes import endpoints.
- Core → Export: routes · Core exposes export endpoints.
- Core → Storages: routes · Core exposes storage connectors and proxy APIs.
- Core → ML: routes · Core exposes ML backend integration endpoints.
- Core → Organizations: routes · Core exposes organization-scoped APIs and views.
- Core → Users: routes · Core exposes account and user endpoints.
- Core → JWT auth: protects · JWT auth participates in the shared request boundary.
- Core → Session policy: enforces · Session policy constrains authenticated access.
- Projects → Tasks: owns · Projects define task lifecycle context and labeling configuration.
- Tasks → FSM: transitions · Task and annotation state changes are mediated by FSM transitions.
- Projects → FSM: transitions · Project lifecycle and state inference flow through FSM.
- Tasks → Data manager: feeds · Task records and annotations power browsing and action workflows.
- Import → Tasks: creates · Imported data becomes tasks and task attachments.
- Export → Tasks: reads · Exports are assembled from task, annotation, and prediction data.
- Storages → DB/Redis/ML: stores · Storage backends and proxies depend on external file/object systems.
- ML → DB/Redis/ML: calls · Model backends are external services connected by API.
- Model runs → ML: executes · Model run records coordinate backend execution and results.
- Providers → DB/Redis/ML: connects · Provider connections reach external model services.
- Label Studio → Editor: embeds · Main app embeds the annotation editor engine.
- Label Studio → Data manager UI: embeds · Main app embeds the data manager experience.
- Label Studio → Core UI: uses · Main app relies on shared frontend infrastructure.
- Editor → Core: consumes APIs · Editor state and actions are driven by backend APIs.
- Data manager UI → Data manager: consumes APIs · Data manager UI is driven by the backend data manager domain.
- Docs site → Label Studio: documents · Docs mirror product behaviors and feature surface.
- Deploy → Core: packages · Deployment assets package and launch the backend app.
- Deploy → Label Studio: serves · Deployment assets front the product UI and static assets.
- Deploy → DB/Redis/ML: depends on · Containers and entrypoints assume database, cache, storage, and proxy services.
- CI/CD → Deploy: builds · Automation builds images and release artifacts.
- CI/CD → Label Studio: tests · Frontend tests and builds run through CI.
- CI/CD → Core: tests · Backend test suites and migrations run through CI.
- Webhooks → DB/Redis/ML: emits · Outbound hooks notify external systems when internal events occur.