# run-llama/llama_deploy architecture

> Architecture diagram of the GitHub repository run-llama/llama_deploy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/run-llama/llama_deploy
- Repository: https://github.com/run-llama/llama_deploy

## Overview

LlamaDeploy is a deprecated workflow deployment platform: operators configure deployments through the CLI or API, then clients submit tasks and manage sessions against the API server. The server parses deployment configuration, manages workflow services and task execution, and exposes status, task/event, and optional UI-proxy endpoints. The graph also preserves source-management, metrics, and tracing responsibilities. Some modules were not excerpted; edges are limited to relationships visible in excerpts or the source index.

Main entry points: [`llama_deploy/apiserver/routers/deployments.py`](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/deployments.py) (Deployment routes), [`llama_deploy/apiserver/app.py`](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/app.py) (FastAPI app), [`llama_deploy/apiserver/server.py`](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/server.py) (Server lifecycle), [`llama_deploy/client/models/apiserver.py`](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/models/apiserver.py) (API client models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator tools"]
  node_cli["CLI commands<br/>[__init__.py]"]
  node_cli_init["Project init<br/>[init.py]"]
  node_cli_config[("CLI config<br/>[config.py]")]
  node_cli_sessions["Session commands<br/>[sessions.py]"]
end

subgraph group_server["API server"]
  node_app["FastAPI app<br/>[app.py]"]
  node_server_lifecycle["Server lifecycle<br/>[server.py]"]
  node_routes["Deployment routes<br/>[deployments.py]"]
  node_status_routes["Status routes<br/>[status.py]"]
  node_settings["Server settings<br/>[settings.py]"]
  node_tracing["Tracing<br/>[tracing.py]"]
  node_stats["Metrics state<br/>[stats.py]"]
end

subgraph group_runtime["Workflow runtime"]
  node_config_parser["Config parser"]
  node_manager["Deployment manager<br/>[deployment.py]"]
  node_source_base["Source manager interface<br/>[base.py]"]
  node_source_git["Git source<br/>[git.py]"]
  node_source_local["Local source<br/>[local.py]"]
  node_workflow_services["Workflow services<br/>[deployment.py]"]
  node_task_session["Tasks and sessions<br/>[deployments.py]"]
end

subgraph group_client["Client and contracts"]
  node_client["Python client<br/>[client.py]"]
  node_client_api["API client models<br/>[apiserver.py]"]
  node_client_base["HTTP transport<br/>[base.py]"]
  node_contracts["Task/session types<br/>[core.py]"]
  node_api_types["API status types<br/>[apiserver.py]"]
end

node_operator(("Operator"))
node_ui_service["Deployment UI"]
node_metrics_exporter["Metrics exporter"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"offers init"| node_cli_init
node_cli -->|"offers sessions"| node_cli_sessions
node_cli_sessions -->|"loads profile"| node_cli_config
node_cli_sessions -->|"creates client"| node_client
node_cli_init -->|"uses schema"| node_config_parser
node_client -->|"exposes API"| node_client_api
node_client_api -->|"sends requests"| node_client_base
node_client_api -->|"uses payloads"| node_contracts
node_client_api -->|"uses status"| node_api_types
node_client_api -.->|"calls HTTP API"| node_app
node_app -->|"mounts routes"| node_routes
node_app -->|"mounts routes"| node_status_routes
node_app -->|"sets lifespan"| node_server_lifecycle
node_app -->|"configures tracing"| node_tracing
node_server_lifecycle -->|"starts and deploys"| node_manager
node_server_lifecycle -->|"parses startup config"| node_config_parser
node_server_lifecycle -->|"reads settings"| node_settings
node_server_lifecycle -->|"updates state"| node_stats
node_routes -->|"deploys config"| node_manager
node_routes -->|"parses uploads"| node_config_parser
node_routes -->|"runs workflows"| node_workflow_services
node_routes -->|"serves task operations"| node_task_session
node_routes -->|"proxies UI traffic"| node_ui_service
node_manager -->|"uses source interface"| node_source_base
node_source_base -->|"uses source schema"| node_config_parser
node_source_git -->|"implements interface"| node_source_base
node_source_local -->|"implements interface"| node_source_base
node_settings -.->|"enables exporter"| node_metrics_exporter

click node_cli "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/__init__.py"
click node_cli_init "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/init.py"
click node_cli_config "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/internal/config.py"
click node_cli_sessions "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/sessions.py"
click node_client "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/client.py"
click node_client_api "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/models/apiserver.py"
click node_client_base "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/base.py"
click node_contracts "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/types/core.py"
click node_api_types "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/types/apiserver.py"
click node_app "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/app.py"
click node_server_lifecycle "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/server.py"
click node_routes "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/deployments.py"
click node_status_routes "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/status.py"
click node_settings "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/settings.py"
click node_tracing "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/tracing.py"
click node_stats "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/stats.py"
click node_config_parser "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment_config_parser.py"
click node_manager "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment.py"
click node_source_base "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/base.py"
click node_source_git "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/git.py"
click node_source_local "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/local.py"
click node_workflow_services "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment.py"
click node_task_session "https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/deployments.py"

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_cli,node_cli_init,node_cli_config,node_cli_sessions,node_ui_service toneBlue
class node_app,node_server_lifecycle,node_routes,node_status_routes,node_settings,node_tracing,node_stats toneAmber
class node_config_parser,node_manager,node_source_base,node_source_git,node_source_local,node_workflow_services,node_task_session toneMint
class node_client,node_client_api,node_client_base,node_contracts,node_api_types toneRose
class node_operator,node_metrics_exporter toneIndigo
```

## Components

### Operator tools

- [CLI commands](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/__init__.py): `llama_deploy/cli/__init__.py`
- [Project init](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/init.py): `llama_deploy/cli/init.py`
- [CLI config](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/internal/config.py): `llama_deploy/cli/internal/config.py`
- [Session commands](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/cli/sessions.py): `llama_deploy/cli/sessions.py`

### API server

- [FastAPI app](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/app.py): `llama_deploy/apiserver/app.py`
- [Server lifecycle](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/server.py): `llama_deploy/apiserver/server.py`
- [Deployment routes](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/deployments.py): `llama_deploy/apiserver/routers/deployments.py`
- [Status routes](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/status.py): `llama_deploy/apiserver/routers/status.py`
- [Server settings](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/settings.py): `llama_deploy/apiserver/settings.py`
- [Tracing](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/tracing.py): `llama_deploy/apiserver/tracing.py`
- [Metrics state](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/stats.py): `llama_deploy/apiserver/stats.py`

### Workflow runtime

- [Config parser](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment_config_parser.py): `llama_deploy/apiserver/deployment_config_parser.py`
- [Deployment manager](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment.py): `llama_deploy/apiserver/deployment.py`
- [Source manager interface](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/base.py): `llama_deploy/apiserver/source_managers/base.py`
- [Git source](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/git.py): `llama_deploy/apiserver/source_managers/git.py`
- [Local source](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/source_managers/local.py): `llama_deploy/apiserver/source_managers/local.py`
- [Workflow services](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/deployment.py): `llama_deploy/apiserver/deployment.py`
- [Tasks and sessions](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/apiserver/routers/deployments.py): `llama_deploy/apiserver/routers/deployments.py`

### Client and contracts

- [Python client](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/client.py): `llama_deploy/client/client.py`
- [API client models](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/models/apiserver.py): `llama_deploy/client/models/apiserver.py`
- [HTTP transport](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/client/base.py): `llama_deploy/client/base.py`
- [Task/session types](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/types/core.py): `llama_deploy/types/core.py`
- [API status types](https://github.com/run-llama/llama_deploy/blob/main/llama_deploy/types/apiserver.py): `llama_deploy/types/apiserver.py`

### Other components

- **Operator**
- **Deployment UI**
- **Metrics exporter**

## Connections

- Operator → CLI commands: runs commands
- CLI commands → Project init: offers init (evidence: `llama_deploy/cli/__init__.py`)
- CLI commands → Session commands: offers sessions (evidence: `llama_deploy/cli/__init__.py`)
- Session commands → CLI config: loads profile (evidence: `llama_deploy/cli/sessions.py`)
- Session commands → Python client: creates client (evidence: `llama_deploy/cli/sessions.py`)
- Project init → Config parser: uses schema (evidence: `llama_deploy/cli/init.py`)
- Python client → API client models: exposes API (evidence: `llama_deploy/client/client.py`)
- API client models → HTTP transport: sends requests (evidence: `llama_deploy/client/models/apiserver.py`)
- API client models → Task/session types: uses payloads (evidence: `llama_deploy/client/models/apiserver.py`)
- API client models → API status types: uses status (evidence: `llama_deploy/client/models/apiserver.py`)
- API client models → FastAPI app: calls HTTP API (evidence: `llama_deploy/client/models/apiserver.py`)
- FastAPI app → Deployment routes: mounts routes (evidence: `llama_deploy/apiserver/app.py`)
- FastAPI app → Status routes: mounts routes (evidence: `llama_deploy/apiserver/app.py`)
- FastAPI app → Server lifecycle: sets lifespan (evidence: `llama_deploy/apiserver/app.py`)
- FastAPI app → Tracing: configures tracing (evidence: `llama_deploy/apiserver/app.py`)
- Server lifecycle → Deployment manager: starts and deploys (evidence: `llama_deploy/apiserver/server.py`)
- Server lifecycle → Config parser: parses startup config (evidence: `llama_deploy/apiserver/server.py`)
- Server lifecycle → Server settings: reads settings (evidence: `llama_deploy/apiserver/server.py`)
- Server lifecycle → Metrics state: updates state (evidence: `llama_deploy/apiserver/server.py`)
- Deployment routes → Deployment manager: deploys config (evidence: `llama_deploy/apiserver/routers/deployments.py`)
- Deployment routes → Config parser: parses uploads (evidence: `llama_deploy/apiserver/routers/deployments.py`)
- Deployment routes → Workflow services: runs workflows (evidence: `llama_deploy/apiserver/routers/deployments.py`)
- Deployment routes → Tasks and sessions: serves task operations (evidence: `llama_deploy/apiserver/routers/deployments.py`)
- Deployment routes → Deployment UI: proxies UI traffic (evidence: `llama_deploy/apiserver/routers/deployments.py`)
- Deployment manager → Source manager interface: uses source interface (evidence: `llama_deploy/apiserver/deployment.py`)
- Source manager interface → Config parser: uses source schema (evidence: `llama_deploy/apiserver/source_managers/base.py`)
- Git source → Source manager interface: implements interface (evidence: `llama_deploy/apiserver/source_managers/git.py`)
- Local source → Source manager interface: implements interface (evidence: `llama_deploy/apiserver/source_managers/local.py`)
- Server settings → Metrics exporter: enables exporter
