> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> Understanding CVAT's system architecture and components

CVAT is a complex distributed system built with modern technologies. This guide provides an overview of the architecture, key components, and how they interact.

## High-Level Architecture

CVAT follows a microservices architecture with these main components:

```
┌─────────────┐
│   Browser   │
└──────┬──────┘
       │ HTTPS
       ▼
┌─────────────┐
│   Traefik   │  ← Reverse Proxy
└──────┬──────┘
       │
       ├────────────────┬────────────────┬───────────────┐
       ▼                ▼                ▼               ▼
┌────────────┐   ┌────────────┐   ┌──────────┐   ┌─────────┐
│  Frontend  │   │  Backend   │   │   OPA    │   │ Vector  │
│   (UI)     │   │  (Django)  │   │ (AuthZ)  │   │ (Logs)  │
└────────────┘   └──────┬─────┘   └──────────┘   └─────────┘
                        │
        ┌───────────────┼───────────────┬──────────────┐
        ▼               ▼               ▼              ▼
   ┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
   │PostgreSQL│   │  Redis   │   │ClickHouse│   │ Kvrocks  │
   │   (DB)   │   │ (Cache)  │   │(Analytics)│   │ (Cache)  │
   └─────────┘   └──────────┘   └──────────┘   └──────────┘
                        │
                        ▼
                ┌───────────────┐
                │  RQ Workers   │
                │ (Background)  │
                └───────────────┘
```

## Core Components

### Frontend (cvat-ui)

**Technology Stack:**

* React 18
* TypeScript
* Redux for state management
* Ant Design for UI components
* Webpack for bundling

**Key Packages:**

#### cvat-ui

Main UI application providing:

* Task and project management interfaces
* Annotation workspace
* User management
* Analytics dashboards
* Settings and configuration

**Location**: `cvat-ui/src/`

#### cvat-core

Core business logic and API client:

* REST API communication
* Data models (Task, Job, Project, Annotation)
* State management
* Authentication handling

**Location**: `cvat-core/src/`

#### cvat-canvas

2D annotation canvas:

* Drawing tools (rectangle, polygon, polyline, points, ellipse, mask)
* Interaction handling (drag, resize, rotate)
* Zoom and pan
* SVG-based rendering

**Location**: `cvat-canvas/src/`

#### cvat-canvas3d

3D annotation canvas:

* Point cloud rendering
* 3D cuboid annotations
* Camera views (perspective, top, side, front)
* Three.js-based rendering

**Location**: `cvat-canvas3d/src/`

#### cvat-data

Data handling utilities:

* Frame providers
* Data chunking
* Video/image processing
* Compression utilities

**Location**: `cvat-data/src/`

### Backend (cvat)

**Technology Stack:**

* Python 3.10+
* Django 4.2
* Django REST Framework
* Uvicorn (ASGI server)
* RQ (Redis Queue) for background tasks

**Django Apps Structure:**

The backend is organized into Django apps in `cvat/apps/`:

#### engine

Core business logic:

* Models: Task, Job, Project, Label, Annotation
* API endpoints for CRUD operations
* Annotation management
* Frame caching and serving

**Location**: `cvat/apps/engine/`

#### dataset\_manager

Import/export functionality:

* Format converters (COCO, YOLO, Pascal VOC, etc.)
* Annotation transformations
* Dataset validation

**Location**: `cvat/apps/dataset_manager/`

#### organizations

Multi-tenancy support:

* Organization management
* Membership handling
* Resource isolation

**Location**: `cvat/apps/organizations/`

#### iam (Identity and Access Management)

Authentication and authorization:

* User management
* Permission system
* Role-based access control
* Integration with OPA

**Location**: `cvat/apps/iam/`

#### quality\_control

Annotation quality features:

* Quality reports
* Conflict detection
* Inter-annotator agreement
* Honeypot frames

**Location**: `cvat/apps/quality_control/`

#### consensus

Consensus annotations:

* Replica job management
* Annotation merging
* Agreement calculation

**Location**: `cvat/apps/consensus/`

#### lambda\_manager

Serverless function integration:

* Auto-annotation with AI models
* Function management
* Request handling

**Location**: `cvat/apps/lambda_manager/`

#### webhooks

Webhook system:

* Event notifications
* Webhook configuration
* Delivery management

**Location**: `cvat/apps/webhooks/`

#### events

Event tracking and analytics:

* User action logging
* Event aggregation
* Analytics data export

**Location**: `cvat/apps/events/`

### Background Workers (RQ)

CVAT uses Redis Queue for asynchronous task processing:

#### cvat\_worker\_import

Handles annotation imports:

* Parses uploaded files
* Validates annotations
* Inserts data into database

#### cvat\_worker\_export

Handles dataset exports:

* Converts annotations to target format
* Packages data
* Generates download archives

#### cvat\_worker\_annotation

Handles auto-annotation:

* Calls serverless functions
* Processes model predictions
* Creates annotations from results

#### cvat\_worker\_quality\_reports

Processes quality reports:

* Compares annotations
* Calculates metrics
* Generates reports

#### cvat\_worker\_consensus

Handles consensus merging:

* Aggregates replica annotations
* Calculates agreement scores
* Merges annotations

### Data Storage

#### PostgreSQL

**Purpose**: Primary relational database

**Stores**:

* User accounts and permissions
* Tasks, jobs, and projects
* Labels and annotations
* Organizations and memberships
* Audit logs

**Configuration**: `docker-compose.yml`

#### Redis (In-Memory)

**Purpose**: Caching and RQ job queue

**Stores**:

* Session data
* Cached API responses
* RQ job queue
* Temporary data

**Configuration**: `cvat_redis_inmem` service

#### Kvrocks (On-Disk)

**Purpose**: Persistent cache for media data

**Stores**:

* Compressed image chunks
* Video frames
* Cached media files

**Configuration**: `cvat_redis_ondisk` service

#### ClickHouse

**Purpose**: Analytics and event storage

**Stores**:

* User events
* Action logs
* Performance metrics
* Analytics aggregations

**Configuration**: `cvat_clickhouse` service

### Supporting Services

#### Traefik

**Purpose**: Reverse proxy and load balancer

**Features**:

* HTTPS termination
* Request routing
* Access logging
* Rate limiting

#### OPA (Open Policy Agent)

**Purpose**: Policy-based authorization

**Features**:

* Fine-grained access control
* Policy evaluation
* Rule-based permissions

**Location**: `cvat/apps/iam/rules/`

#### Vector

**Purpose**: Log aggregation and forwarding

**Features**:

* Collects container logs
* Transforms log data
* Forwards to analytics systems

## Data Flow

### Annotation Creation Flow

1. User draws annotation in UI (cvat-canvas)
2. Canvas dispatches Redux action
3. cvat-core serializes annotation
4. API request sent to backend
5. Django view validates data
6. OPA checks permissions
7. Data saved to PostgreSQL
8. Event logged to ClickHouse
9. Response returned to frontend
10. Redux state updated
11. UI re-renders

### Task Creation Flow

1. User submits task form
2. Files uploaded via TUS protocol
3. Backend creates Task record
4. Job creation queued in RQ
5. Worker processes media:
   * Extracts frames from video
   * Generates thumbnails
   * Creates chunks
   * Compresses and caches
6. Jobs created and assigned
7. Task marked as ready
8. User notified

### Export Flow

1. User requests dataset export
2. Backend queues export job
3. Worker fetches annotations
4. Format converter transforms data
5. Files packaged into archive
6. Archive stored temporarily
7. Download link provided
8. User downloads file

## API Design

CVAT uses RESTful API design:

### Endpoints Structure

```
/api/
  ├── auth/          # Authentication
  ├── users/         # User management
  ├── projects/      # Projects
  ├── tasks/         # Tasks
  ├── jobs/          # Jobs
  ├── labels/        # Labels
  ├── issues/        # Review issues
  ├── comments/      # Comments
  ├── organizations/ # Organizations
  ├── cloudstorages/ # Cloud storage
  ├── lambda/        # Serverless functions
  ├── webhooks/      # Webhook management
  ├── events/        # Event logs
  └── schema/        # OpenAPI schema
```

### Authentication

* **Session authentication**: For browser-based access
* **Token authentication**: For API/SDK access (being deprecated)
* **Access tokens**: New token system with expiration

## Frontend Architecture

### State Management

CVAT uses Redux with this structure:

```
Store
├── auth          # Authentication state
├── tasks         # Task list and details
├── jobs          # Job list and details
├── projects      # Project list and details
├── annotations   # Current annotation state
├── canvas        # Canvas state (zoom, mode, etc.)
├── settings      # User preferences
├── notifications # UI notifications
└── plugins       # Plugin system state
```

### Component Structure

```
cvat-ui/src/
├── components/   # Presentational components
├── containers/   # Connected containers
├── actions/      # Redux actions
├── reducers/     # Redux reducers
├── utils/        # Utility functions
└── assets/       # Static assets
```

## Security

### Authentication Flow

1. User logs in with credentials
2. Django creates session
3. Session ID stored in cookie
4. Cookie sent with each request
5. Backend validates session
6. OPA evaluates permissions
7. Request allowed or denied

### Authorization (OPA)

OPA policies define permissions:

```rego theme={null}
allow {
    input.auth.user.is_staff
}

allow {
    input.auth.user.id == input.resource.owner.id
}

allow {
    input.resource.organization.id in input.auth.user.organizations
    input.auth.user.has_perm["view_task"]
}
```

## Scalability

CVAT can scale horizontally:

* **Frontend**: Served statically, can use CDN
* **Backend**: Multiple server instances behind load balancer
* **Workers**: Scale worker count based on queue depth
* **Database**: PostgreSQL replication and read replicas
* **Cache**: Redis Cluster or Kvrocks sharding

## Development Workflow

1. Clone repository
2. Start development environment
3. Make changes to code
4. Frontend: Hot-reload automatically
5. Backend: Restart container or use debugger
6. Run tests
7. Submit pull request

## Deployment

CVAT supports multiple deployment options:

* **Docker Compose**: Simple single-server deployment
* **Kubernetes/Helm**: Production-grade orchestration
* **Cloud**: AWS, GCP, Azure with managed services

See the [installation documentation](https://docs.cvat.ai/docs/administration/basics/installation/) for details.

## Next Steps

* Review the [code style guidelines](/contributing/code-style)
* Learn about [testing](/contributing/testing)
* Read the [pull request guide](/contributing/pull-requests)
* Explore the [API documentation](https://docs.cvat.ai/docs/api_sdk/api/)