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

# Architecture

> High-level architecture for the Fleet Manager API, agents, workers, and site topology.

Fleet Manager is designed as a control plane for hardware lifecycle workflows.
The API is the operator entrypoint, while workflow workers and background agents do the
long-running and integration-heavy work outside the request path.

## Core Building Blocks

* **Fleet Manager API** provides the main control plane and serves data from Fleet Manager's own database
* **Workflow Agent** synchronises workflow intent and [Temporal](../start-here/glossary#temporal) status back into Fleet Manager
* **[NetBox](../start-here/glossary#netbox) Agent** synchronises inventory and site data from NetBox
* **Temporal Workers** run durable workflow and activity logic
* **PostgreSQL** stores Fleet Manager's queryable state and API-facing data model

## Why Fleet Manager Uses Agents

Fleet Manager does not want API endpoints to fan out directly to external systems for every
request. The main architectural reason is query shape and scale.

For example, showing a page of jobs should not require one list call plus one live status call
per job against Temporal. Instead:

* agents poll or otherwise reconcile external systems in the background
* Fleet Manager stores the synchronised state in its own database
* the API serves operators from that local state

This avoids N+1 request patterns, reduces coupling to external APIs, and keeps the UI usable
even when an upstream system is degraded.

## Workflow Model

Fleet Manager's long-running orchestration is centred on Temporal.
That choice was driven by the need for:

* durable workflows that survive restarts
* retryable and heartbeated activities for unreliable infrastructure
* cancellation and manual-intervention points
* long-running execution for multi-stage enrolment and [burn-in](../start-here/glossary#burn-in) jobs

The workflow platform is intended to handle both current provisioning flows and future day-2
operations such as remediation, quarantine, or hardware triage workflows.

## Hub and Satellite Topology

Fleet Manager is deployed as a hub plus one or more satellites.

* The **hub** hosts the API and presents a single global view of the [fleet](../start-here/glossary#fleet)
* Each **satellite** runs site-local workflow workers and other components close to the hardware and credentials they need
* Satellites use their own vault selection, PKI material, and deployment-specific configuration

This keeps trust boundaries explicit and lets sites be added or rotated independently.

## External Systems

A typical deployment integrates with:

* **NetBox** as the inventory source of truth
* **OpenStack** services such as [Ironic](../start-here/glossary#ironic), [Nova](../start-here/glossary#nova), and [Placement](../start-here/glossary#placement)
* **[DHCP](../start-here/glossary#dhcp) infrastructure** used during provisioning
* **[1Password](../start-here/glossary#1password)** and related secret-management workflows
* **[SLURM](../start-here/glossary#slurm)** for hardware-test execution
* **Prometheus and Grafana** for metrics and logs

For the full map of [device](../start-here/glossary#node) status axes, conditions, and per-integration write paths, see
[Device State Machines](./device-state-machines).

## Development Implications

Some architectural rules follow directly from this design:

* long-running work should not happen inside API requests
* external I/O belongs in activities or agents, not in Temporal workflow definitions
* Fleet Manager's API layer should depend on its own typed models rather than ad hoc external payloads
* site-specific configuration belongs with the deployment, not in code-time branching


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.