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

# Architecture

> How the Avala platform is structured

This page provides an overview of how the Avala platform is organized and how its components interact.

<img src="https://mintcdn.com/avala/QI4wcFsXqwG8KGbR/images/reference/architecture-system-overview-light.svg?fit=max&auto=format&n=QI4wcFsXqwG8KGbR&q=85&s=2e7d5ce34b4db810adebeec241a97e6a" alt="Avala System Architecture" className="block dark:hidden w-full" width="480" height="100" data-path="images/reference/architecture-system-overview-light.svg" />

<img src="https://mintcdn.com/avala/QI4wcFsXqwG8KGbR/images/reference/architecture-system-overview.svg?fit=max&auto=format&n=QI4wcFsXqwG8KGbR&q=85&s=92d58f56f725d7b1a535b1d95323fe10" alt="Avala System Architecture" className="hidden dark:block w-full" width="480" height="100" data-path="images/reference/architecture-system-overview.svg" />

## System Overview

<Steps>
  <Step title="Mission Control" icon="browser">
    Web UI at [avala.ai](https://avala.ai) — Visualization, Annotation, Project Management, Quality Control, Dataset Management
  </Step>

  <Step title="Visualization Engine" icon="display">
    GPU-accelerated rendering — Multi-Sensor Viewer, 3D Point Cloud Viewer, Gaussian Splat Viewer, WebGPU/WebGL rendering pipeline
  </Step>

  <Step title="REST API" icon="server">
    `api.avala.ai/api/v1` — Datasets, Projects, Tasks, Exports, Organizations. Access via direct HTTP/cURL, Python SDK, TypeScript SDK, or CLI.
  </Step>

  <Step title="Backend Services" icon="gears">
    Asynchronous processing — MCAP Parsing, Video Conversion, Export Generation, Task Processing, Inference Pipeline
  </Step>

  <Step title="Storage" icon="database">
    Persistent data — Dataset Files, Annotations, Exports, Model Artifacts
  </Step>
</Steps>

## Components

### Mission Control

Mission Control is Avala's web application at [avala.ai](https://avala.ai). It provides:

* **Data Visualization** — GPU-accelerated viewers for exploring sensor data before, during, and after annotation. Multi-sensor playback, 3D point cloud rendering, and Gaussian Splat scene navigation — all in the browser.
* **Annotation Editor** — Purpose-built tools for labeling images, video, point clouds, and multi-sensor data with support for bounding boxes, polygons, cuboids, segmentation, polylines, and keypoints.
* **Project Management** — Create and configure annotation projects, define label taxonomies, assign work to team members, and monitor progress.
* **Quality Control** — Review submitted annotations, flag issues, track acceptance rates, and run consensus workflows.
* **Dataset Management** — Upload data, organize items into sequences, browse and search datasets, and manage access permissions.

### Visualization Engine

The visualization engine runs in the browser and provides GPU-accelerated rendering for sensor data:

* **Multi-Sensor Viewer** — Synchronized playback of MCAP and ROS recordings with eight panel types: Image, 3D / Point Cloud, Plot, Raw Messages, Log, Map, Gauge, and State Transitions. Automatic topic detection and smart layout composition arrange panels based on your data.
* **3D Point Cloud Viewer** — Renders LiDAR data with six visualization modes (Neutral, Intensity, Rainbow, Label, Panoptic, Image Projection). Bird's-eye view, perspective, and side views. WebGPU compute shaders handle frustum culling and level-of-detail rendering for high frame rates on dense scans.
* **Gaussian Splat Viewer** — WebGPU-accelerated rendering of 3D Gaussian Splat scene reconstructions. GPU radix sorting, buffer pooling, and pipeline precompilation deliver real-time navigation through photorealistic environments.
* **Rendering Pipeline** — WebGPU is preferred with automatic WebGL fallback for broader browser support. Feature flags control compute shaders, render bundles, and WGSL shader compilation.
* **Multi-Window Layout** — Configurable panel arrangements with drag-and-drop. A tree-based layout system with automatic balancing lets you customize how panels are organized, or let the layout composer build an optimized arrangement from your data.

<Tip>
  The visualization engine requires no plugins or downloads. It runs natively in Chrome 113+, Edge 113+, and other WebGPU-capable browsers, with WebGL fallback for older browsers.
</Tip>

### REST API

The REST API at `api.avala.ai/api/v1` provides programmatic access to every platform capability. All requests authenticate with an API key passed in the `X-Avala-Api-Key` header.

Core resources:

| Resource          | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| **Datasets**      | Create, list, and manage datasets and their items                   |
| **Projects**      | Configure annotation workflows, label taxonomies, and task settings |
| **Tasks**         | Assign, track, and manage individual annotation work units          |
| **Exports**       | Generate and download annotated data in various formats             |
| **Organizations** | Manage teams, members, roles, and permissions                       |

The API follows REST conventions with JSON request and response bodies, cursor-based pagination, and standard HTTP status codes.

### SDKs

You can call the REST API directly from any language using standard HTTP clients (see [REST API](/docs/sdks/rest-api)), or use the official SDKs:

* **Python SDK** (`pip install avala`) — Sync and async clients, Pydantic models, automatic pagination, typed exceptions, CLI tool.
* **TypeScript SDK** (`npm install @avala-ai/sdk`) — Fully typed client with Promise-based API for Node.js and edge runtimes.
* **CLI** (`curl -fsSL https://avala.ai/install.sh | bash`) — Manage datasets, projects, exports, and storage from your terminal.

See the [SDKs overview](/docs/sdks/overview) for details.

### Backend Services

Backend services handle asynchronous processing that powers the platform:

* **MCAP Parsing** — Extracts and synchronizes sensor streams from MCAP recordings, detects message types, and builds frame indices for the multi-sensor viewer.
* **Video Conversion** — Splits uploaded video files into frame sequences for visualization and annotation.
* **Export Generation** — Produces downloadable exports in JSON, COCO, KITTI, and other formats.
* **Task Processing** — Generates and distributes annotation tasks based on project configuration.
* **Inference Pipeline** — Runs model inference for AI-assisted annotation and pre-labeling.

### Storage

Storage manages all persistent data:

* **Dataset files** — Raw images, video frames, point clouds, and MCAP recordings.
* **Annotations** — Labeled data produced by annotators (bounding boxes, polygons, cuboids, masks).
* **Exports** — Generated export files available for download.
* **Model artifacts** — Weights and configurations for inference models used in AI-assisted labeling.

### MCP Server

The MCP (Model Context Protocol) server exposes Avala tools to AI assistants like Claude, Cursor, and VS Code Copilot. It enables natural-language interaction with datasets, projects, and exports without leaving your development environment.

<Tip>
  The `@avala-ai/mcp-server` package is available on npm. Install with `npm install -g @avala-ai/mcp-server` or use `npx`. See the [MCP setup guide](/docs/integrations/mcp-setup) for installation instructions.
</Tip>

## How Components Interact

1. **Users** interact with Avala through Mission Control (web UI) or programmatically through the REST API and SDKs.
2. **Mission Control** loads data through the REST API and renders it using the visualization engine directly in the browser — no server-side rendering required.
3. **All client interfaces** communicate with the same REST API, so actions taken in Mission Control are immediately visible via the API and vice versa.
4. **The REST API** validates requests, manages resources, and dispatches work to backend services for asynchronous processing.
5. **Backend services** process tasks (MCAP parsing, video conversion, export generation) and write results back to storage.

## Next Steps

<CardGroup cols={2}>
  <Card title="" icon="square-terminal" href="/docs/api-reference/overview">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>API Reference</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Base URL, authentication, endpoints, and response format.</p>
  </Card>

  <Card title="" icon="sparkles" href="/docs/getting-started/mcp">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Use Avala with AI</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Connect Avala to Claude, Cursor, and VS Code with MCP.</p>
  </Card>

  <Card title="" icon="database" href="/docs/getting-started/data-types">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Data Types</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Visualization capabilities and annotation tools for each data type.</p>
  </Card>

  <Card title="" icon="lightbulb" href="/docs/getting-started/concepts">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Core Concepts</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Viewers, panels, layouts, timelines, and other platform concepts.</p>
  </Card>
</CardGroup>