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

# XMS Architecture

> How the Xloud Migration Suite is structured — control plane, migration workers, disk transport libraries, and integration with Xloud platform services.

## Overview

XMS is a service inside the Xloud platform. It has a control plane that
exposes the user-facing APIs and a pool of migration workers that execute the
actual disk transport and guest conversion work. Both run alongside the rest
of Xloud and integrate with the platform's identity, storage, compute, and
networking services.

***

## Component Map

```mermaid theme={null}
graph TB
    subgraph "Xloud Dashboard"
      UI["Migration Panel"]
    end
    subgraph "XMS Control Plane"
      API["XMS API"]
      ORCH["Job Orchestrator"]
      STATE[("Job State Store")]
    end
    subgraph "Migration Workers"
      W1["Worker 1"]
      W2["Worker 2"]
      WN["Worker N"]
    end
    subgraph "Source"
      VC["vCenter / ESXi"]
    end
    subgraph "Xloud Services"
      KS["Identity"]
      CI["Block Storage"]
      NO["Compute"]
      NE["Networking"]
    end

    UI --> API
    API --> ORCH
    ORCH <--> STATE
    ORCH --> W1
    ORCH --> W2
    ORCH --> WN
    W1 --> VC
    W2 --> VC
    WN --> VC
    W1 --> CI
    W2 --> CI
    WN --> CI
    API --> KS
    API --> CI
    API --> NO
    API --> NE
```

| Component            | Responsibility                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Migration Panel**  | User-facing UI in the Xloud Dashboard — sources, discovery, preflight, jobs, events                                            |
| **XMS API**          | REST API that the dashboard and CLI call. Validates requests, enforces project scoping, and hands jobs off to the orchestrator |
| **Job Orchestrator** | Assigns jobs to workers, tracks phase transitions, and publishes events                                                        |
| **Job State Store**  | Authoritative store of every job's state, progress, and event history                                                          |
| **Migration Worker** | Executes the disk transport and guest conversion pipeline for a single job                                                     |

***

## Workload Data Flow

### Cold Migration

```mermaid theme={null}
graph LR
    S["Source VM<br/>(powered off)"] -->|vSphere API| W["Migration Worker"]
    W -->|Xloud Block Storage API| V["Target Volume"]
    W -->|Xloud Compute API| I["Target Instance"]
    V --> I
```

1. Worker opens a disk transport session against the source via vSphere API
2. Worker creates an empty target volume through Xloud Block Storage
3. Disk data is streamed from the source and written into the target volume
4. Guest conversion runs against the target volume
5. The target instance is created and attached to the target volume

### Warm Migration

```mermaid theme={null}
graph LR
    S["Source VM<br/>(running)"] -->|vSphere API + CBT| W["Migration Worker"]
    W -->|Xloud Block Storage API| V["Target Volume"]
    W -.->|incremental syncs| V
    V --> I["Target Instance<br/>(at cutover)"]
```

1. Worker takes a baseline snapshot on the source
2. Full sync copies every block into the target volume
3. Between syncs, the job sits idle in the **Ready** state
4. Each incremental sync reads only the blocks that changed since the last
   baseline and writes them to the same offsets in the target volume
5. At cutover, a final incremental sync and guest conversion run before the
   target instance is launched

***

## Disk Transport Libraries

XMS uses the vSphere storage APIs and a disk transport library to read
source VM disks efficiently. The library version is selected to match the
source vSphere version and is an operator-managed component of the XMS
deployment.

<Tip>
  The transport library is the same code path for cold migrations, warm full
  syncs, and warm incremental syncs — only the set of blocks read differs
  between the three cases.
</Tip>

***

## Integration with Xloud Services

| Xloud Service     | Purpose                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Identity**      | Project scoping, token validation, and role enforcement for every XMS API call                                                                    |
| **Block Storage** | Target volumes are created and written through the platform's block storage API, so they are indistinguishable from volumes created any other way |
| **Compute**       | The target instance is a normal Xloud compute instance — flavors, networking, and metadata all apply as usual                                     |
| **Networking**    | Target instance NICs are attached to target Xloud networks using the network mapping chosen at submit time                                        |

Because migrated volumes and instances are native Xloud objects, the standard
Xloud tooling — quotas, volume types, availability zones, security groups,
snapshots, backups — applies automatically.

***

## Multi-Source, Multi-Project

A single XMS deployment can:

* Register multiple source environments (one or more vCenters, standalone
  ESXi hosts)
* Run concurrent migration jobs across different sources
* Target different Xloud projects for different migrations

<Note>
  Project scoping is enforced at the API layer using the caller's identity
  token — users only see migrations for projects they are authorized to access.
</Note>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Prerequisites" href="/services/migration/admin-guide/prerequisites" color="#197560">
    Platform, project, quota, and identity prerequisites
  </Card>

  <Card title="Network Ports" href="/services/migration/admin-guide/network-ports" color="#197560">
    Which ports must be reachable between XMS, sources, and targets
  </Card>

  <Card title="Capacity Planning" href="/services/migration/admin-guide/capacity-planning" color="#197560">
    Sizing XMS for concurrent migrations and multi-wave campaigns
  </Card>
</CardGroup>