How humansignal/label-studio works
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: core Core · labelstudio Label Studio · tasks Tasks · deploy Deploy
Components 27
Backend
Django application, domain apps, workflow engine, and integrations.
- manage.py · Command entrypoint for Django management and local server operations.
label_studio/manage.py - server.py · Process bootstrap for running the Label Studio application.
label_studio/server.py - Core · Shared backend infrastructure: settings, URLs, middleware, permissions, storage helpers, logging, and static serving.
label_studio/core - Projects · Project lifecycle, labeling config, settings, summaries, and signals.
label_studio/projects - Tasks · Tasks, annotations, predictions, locks, completion history, and task-level APIs.
label_studio/tasks - Data manager · Task browsing, filtering, bulk actions, and data management APIs.
label_studio/data_manager - FSM · Explicit finite-state transitions and lifecycle inference for projects, tasks, and annotations.
label_studio/fsm - Import · Task/data ingestion and upload flows.
label_studio/data_import - Export · Result export and converted-format handling.
label_studio/data_export - Storages · Local, cloud, and proxy storage integrations for import/export and remote data access.
label_studio/io_storages - ML · External ML backend integration for predictions and model-assisted labeling.
label_studio/ml - Model runs · Model runs, versions, and project-linked model execution records.
label_studio/ml_models - Providers · Connections to third-party model providers and available model catalogs.
label_studio/ml_model_providers - Users · User accounts, preferences, hotkeys, and activity-related logic.
label_studio/users - Organizations · Organization membership, admin views, and org-scoped access control.
label_studio/organizations - JWT auth · Token-based auth, middleware, and JWT-specific account access.
label_studio/jwt_auth - Session policy · Session timeout and policy enforcement boundary.
label_studio/session_policy - Webhooks · Event hooks for notifying external systems about internal changes.
label_studio/webhooks
Frontend
React/Nx product UI, shared libraries, and annotation editor.
- Label Studio · Main React application for the product UI and page routing.
web/apps/labelstudio - Editor · Core labeling editor with tags, regions, tools, stores, and media-specific interaction models.
web/libs/editor - Data manager UI · Frontend for task tables, filters, bulk actions, and data browsing workflows.
web/libs/datamanager - Core UI · Shared frontend hooks, API providers, utilities, and app-common layers.
web/libs/core - UI kit · Reusable visual components, tokens, dialogs, and app-wide UI primitives.
web/libs/ui
Infra
Deployment, external services, and runtime dependencies.
- Deploy · Dockerfiles, compose stacks, Nginx config, entrypoints, and release scripts.
deploy - CI/CD · GitHub Actions, build/test pipelines, release automation, and quality gates.
.github/workflows - DB/Redis/ML · Primary runtime dependencies: relational database, Redis, object storage, Nginx, auth providers, and external ML services.
Docs
Public documentation and content generation.
- Docs site · Separate documentation runtime with guides, templates, tutorials, and Netlify assets.
docs
Connections 36
- 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.