# opendatalab/labelllm architecture

> Architecture diagram of the GitHub repository opendatalab/labelllm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opendatalab/labelllm
- Repository: https://github.com/opendatalab/labelllm

## Overview

##### Project Type and Purpose
- LabelLLM is a full-stack, web-based data annotation platform.
- The backend is a single FastAPI service (monolith) with RESTful endpoints, background scheduler, and worker processes.
- The frontend consists of three single-page React/TypeScript apps (Login, Operator, Supplier) built with Vite and served via Nginx or a static host.
- Core services include a relational database (PostgreSQL/MySQL), object storage (MinIO), and optional SSO.

##### Main Components
A. Frontend Layer
- Login App (src/apps/login)
- Operator App (src/apps/operator)
- Supplier App (src/apps/supplier)
- Shared UI components (src/components) and utility modules (src/hooks, src/utils)
- Build & Serve: Vite, Rollup, Nginx configuration, Dockerfile
B. API Layer (Backend)
- FastAPI application (app/main.py, app/api/v1/router.py)
- Dependency injection (app/api/deps.py), middleware, security (JWT, CORS)
- CRUD services (app/crud), schemas (app/schemas), Pydantic models
C. Data Layer
- Relational Database (via SQLAlchemy in app/db/session.py, migrations)
- Object Storage: MinIO client (app/client/minio.py) for file uploads/downloads
D. Background Tasks
- Scheduler (app/scheduler/init_scheduler.py) for periodic jobs (stats aggregation, cleanup)
- Worker (backend/worker.py) for asynchronous tasks (file processing, AI pre-annotation)
E. Infrastructure
- Docker Compose orchestrates:
– Backend container (FastAPI + Gunicorn)
– Worker/scheduler container
– MinIO container
– Database container
– Frontend container(s) or static host + Nginx container
- External SSO endpoint (optional)

##### Relationships and Data Flow
1. User (Browser) → Nginx (or Vite dev server) → React SPA (Login/Operator/Supplier)
2. React SPA → REST API calls → FastAPI backend (HTTP port)
3. FastAPI →
- Reads/writes from/to the relational database
- Stores/retrieves files from MinIO
4. Scheduler triggers internal backend tasks (via APScheduler or Celery beat)
5. Worker process picks up jobs (message queue or direct DB polling) for heavy or AI-assisted annotation tasks
6. Backend emits task results to DB → Frontend polling or WebSocket (if implemented)

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (React), API, Service/CRUD, Data
- Clear separation of concerns:
- Routers define endpoints →
- CRUD modules implement business logic →
- Schemas/Pydantic enforce validation →
- Models/ORM map to tables
- Dependency injection in FastAPI for config, DB sessions, security
- Micro-app structure for frontend (three distinct apps sharing common components)
- Infrastructure as code: Docker Compose, Dockerfiles, build scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    Browser["User (Browser)"]:::external

    subgraph "Docker Compose Orchestration"
        direction TB

        %% Frontend Container
        subgraph "Frontend Container"
            direction TB
            LoginApp["Login App"]:::ui
            OperatorApp["Operator App"]:::ui
            SupplierApp["Supplier App"]:::ui
            SharedComponents["Shared UI Components"]:::ui
            SharedHooks["Shared Hooks"]:::ui
            SharedUtils["Shared Utilities"]:::ui
            ViteConfigs["Vite & Rollup Configurations"]:::infra
            NginxConf["Nginx Configuration"]:::infra
            FrontendDocker["Frontend Dockerfile"]:::infra
        end

        %% Backend Container
        subgraph "Backend Container"
            direction TB
            FastAPI["FastAPI App"]:::backend
            subgraph "API Layer"
                Router["API Router"]:::backend
                Deps["Dependency Injection & Security"]:::backend
                Middleware["Middleware"]:::backend
            end
            subgraph "Service Layer"
                CRUD["CRUD Service Layer"]:::backend
                Schemas["Pydantic Schemas"]:::backend
                Models["ORM Models"]:::backend
            end
            subgraph "Data Access"
                DBSession["Database Session & Init"]:::backend
                MinIOClient["MinIO Client"]:::backend
            end
            subgraph "Background Tasks"
                Scheduler["Scheduler for Periodic Tasks"]:::async
                TaskDefs["Scheduler Task Definitions"]:::async
                Worker["Worker Process"]:::async
            end
            GunicornConf["Gunicorn Configuration"]:::backend
            BackendDocker["Backend Dockerfile"]:::infra
        end

        %% Data Stores
        DB["Relational Database"]:::storage
        MinIO["MinIO Storage"]:::storage

        %% External
        ExternalSSO["External SSO"]:::external
    end

    %% Relations - User to Frontend
    Browser -->|"loads SPA via HTTP"| LoginApp
    Browser -->|"loads SPA via HTTP"| OperatorApp
    Browser -->|"loads SPA via HTTP"| SupplierApp

    %% Frontend to Backend
    LoginApp -->|"HTTP/REST"| FastAPI
    OperatorApp -->|"HTTP/REST"| FastAPI
    SupplierApp -->|"HTTP/REST"| FastAPI

    %% Backend internal flows
    FastAPI -->|"routes requests"| Router
    Router -->|"calls"| Deps
    Router -->|"passes through"| Middleware
    Router -->|"invokes"| CRUD
    CRUD -->|"uses schemas/models"| Schemas
    CRUD -->|"uses schemas/models"| Models
    CRUD -->|"opens session via"| DBSession
    DBSession -->|"executes SQL via SQLAlchemy"| DB
    CRUD -->|"stores/retrieves files via"| MinIOClient
    MinIOClient -->|"MinIO API"| MinIO

    %% Background tasks
    Scheduler -->|"schedules"| TaskDefs
    TaskDefs -->|"triggers"| Worker
    Worker -->|".writes results"| DB
    Worker -->|".writes files"| MinIO
    Scheduler -->|".aggregates stats"| DB

    %% Optional SSO
    FastAPI -->|"OAuth/OpenID"| ExternalSSO

    %% Click Events
    click LoginApp "https://github.com/opendatalab/labelllm/tree/main/frontend/src/apps/login"
    click OperatorApp "https://github.com/opendatalab/labelllm/tree/main/frontend/src/apps/operator"
    click SupplierApp "https://github.com/opendatalab/labelllm/tree/main/frontend/src/apps/supplier"
    click SharedComponents "https://github.com/opendatalab/labelllm/tree/main/frontend/src/components"
    click SharedHooks "https://github.com/opendatalab/labelllm/tree/main/frontend/src/hooks"
    click SharedUtils "https://github.com/opendatalab/labelllm/tree/main/frontend/src/utils"
    click ViteConfigs "https://github.com/opendatalab/labelllm/blob/main/frontend/vite.config.dev.ts"
    click ViteConfigs "https://github.com/opendatalab/labelllm/blob/main/frontend/vite.config.prod.ts"
    click ViteConfigs "https://github.com/opendatalab/labelllm/blob/main/frontend/rollup.config.ts"
    click NginxConf "https://github.com/opendatalab/labelllm/blob/main/frontend/nginx.conf"
    click FrontendDocker "https://github.com/opendatalab/labelllm/tree/main/frontend/Dockerfile"
    click FastAPI "https://github.com/opendatalab/labelllm/blob/main/backend/app/main.py"
    click Router "https://github.com/opendatalab/labelllm/blob/main/backend/app/api/router.py"
    click Router "https://github.com/opendatalab/labelllm/blob/main/backend/app/api/v1/router.py"
    click Deps "https://github.com/opendatalab/labelllm/blob/main/backend/app/api/deps.py"
    click Deps "https://github.com/opendatalab/labelllm/blob/main/backend/app/core/security.py"
    click CRUD "https://github.com/opendatalab/labelllm/tree/main/backend/app/crud"
    click Schemas "https://github.com/opendatalab/labelllm/tree/main/backend/app/schemas"
    click Models "https://github.com/opendatalab/labelllm/tree/main/backend/app/models"
    click DBSession "https://github.com/opendatalab/labelllm/blob/main/backend/app/db/session.py"
    click DBSession "https://github.com/opendatalab/labelllm/blob/main/backend/app/db/init_db.py"
    click MinIOClient "https://github.com/opendatalab/labelllm/blob/main/backend/app/client/minio.py"
    click Middleware "https://github.com/opendatalab/labelllm/blob/main/backend/app/middleware/middleware.py"
    click Scheduler "https://github.com/opendatalab/labelllm/blob/main/backend/app/scheduler/init_scheduler.py"
    click TaskDefs "https://github.com/opendatalab/labelllm/blob/main/backend/app/scheduler/task.py"
    click Worker "https://github.com/opendatalab/labelllm/blob/main/backend/app/worker.py"
    click GunicornConf "https://github.com/opendatalab/labelllm/blob/main/backend/app/gunicorn_conf.py"
    click BackendDocker "https://github.com/opendatalab/labelllm/tree/main/backend/Dockerfile"
    click DockerCompose "https://github.com/opendatalab/labelllm/blob/main/docker-compose.yaml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#D8FDD8,stroke:#28a745,stroke-width:1px;
    classDef storage fill:#FFE4B3,stroke:#e36209,stroke-width:1px;
    classDef async fill:#F0D0FF,stroke:#6f42c1,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#E0E0E0,stroke:#6a737d,stroke-width:1px;
    classDef infra fill:#E8E8E8,stroke:#444d56,stroke-width:1px;
```
