---
title: "Architecture"
url: "/docs/concepts/architecture/"
kind: "concept"
summary: "How the Arion process is organized: a services runtime for control work, proxy runtimes for the data path, and channels between them."
---

> Arion site index: [/llms.txt](/llms.txt)

# Architecture

How the Arion process is organized: a services runtime for control work, proxy runtimes for the data path, and channels between them.

Arion runs as a single process split into two kinds of Tokio runtimes — one **services runtime** for control work and one or more **proxy runtimes** for the data path. 

## Why it matters

Configuration changes within Arion never pause traffic: control work (xDS updates, health checks, secret rotation) happens on the services runtime and reaches the data path as messages, not locks. The data path can be scaled by adding whole runtimes rather than sharing one — this is an important option and is key to serving massive traffic volumes in high demand scenarios, described in article [threading model](@/docs/concepts/runtime-and-threading.md).

Arion's operates with fail-fast startup behavior: everything derived from configuration — TLS contexts, clusters, listener factories — is built on the main thread before a single connection can arrive. A bootstrap configuration that cannot be honored stops the process at startup rather than surfacing as a runtime error.

## How it works

At startup the main thread parses the command line, loads the [configuration file](@/docs/concepts/configuration-model.md), and applies environment and flag overrides. It then builds the initial state: the **secret manager** from `static_resources.secrets`, the **cluster registry** from `static_resources.clusters`, and one **listener factory** per static listener. Only when all of that succeeds does it spawn the runtimes.

{{ <figure src="img/docs/architecture.svg" alt="Config file and xDS server feed the services runtime, which fans configuration out to N proxy runtimes over channels" caption="Configuration flows left to right: sources feed the services runtime, which pushes typed changes to every proxy runtime." label="Figure 1." /> }}

The **services runtime** (thread name `services`, sized by `runtime.num_service_threads`) hosts everything that is not per-request work:

- The **xDS client** always starts, even with a purely static config: it pushes the initial listeners to the proxy runtimes, and if `dynamic_resources` names an ADS cluster it opens the gRPC stream, validates incoming resources, and applies or [rejects](@/docs/concepts/envoy-compatibility.md) them.
- The **health check manager** runs active health checks and publishes endpoint health into the cluster registry.
- The [admin server](@/docs/observe/admin-interface.md), [access loggers](@/docs/observe/access-logs.md), and metrics and tracing exporters, when configured.

Each **proxy runtime** (threads `proxy_RT0`, `proxy_RT1`, …) runs one **listeners manager**. It receives listener and route changes over a per-runtime channel and spawns one task per listener; each listener task accepts connections on its own socket and spawns a task per connection. Nothing but data-path work is scheduled on these runtimes.

The two sides meet in three places:

- **Configuration channels.** The services runtime holds one sender per proxy runtime and fans every listener or route change out to all of them. Inside a runtime, the listeners manager re-broadcasts route and TLS updates to the affected listener tasks, which swap their config between requests.
- **Cluster registry.** Clusters, endpoints, and load-balancer state live in a process-wide copy-on-write map; every worker thread reads through a thread-local cache that refreshes only when the version changes, keeping locks off the request path.
- **Secret manager.** TLS certificates and keys are shared behind a read-write lock; rotation via SDS updates the listener tasks through the same channel mechanism as everything else.

## Key terms

- **Services runtime** — the Tokio runtime for control work: xDS, health checks, admin, exporters.
- **Proxy runtime** — a Tokio runtime that runs listeners and serves traffic; there can be one or many.
- **Listeners manager** — the per-runtime component that starts, stops, and updates listener tasks.
- **Cluster registry** — the shared, versioned map of clusters and their endpoints that routing reads.
- **Secret manager** — the shared store of TLS secrets referenced by listeners and clusters.
- **Listener factory** — a validated blueprint of a listener, built at startup or on an xDS update, from which each runtime creates its own listener task.

## Next

- Follow one connection through this machinery in [life of a request](@/docs/concepts/life-of-a-request.md).
- Decide how many proxy runtimes to run in [runtime and threading](@/docs/concepts/runtime-and-threading.md).
- See how the file, flags, and xDS produce the initial state in [the configuration model](@/docs/concepts/configuration-model.md).