# rocm/cvs architecture

> Architecture diagram of the GitHub repository rocm/cvs, 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/rocm/cvs
- Repository: https://github.com/rocm/cvs

## Overview

CVS is an SSH-based suite for end-to-end AMD AI cluster validation, with CLI-driven tests, cluster orchestration, and training/inference workloads producing reports. The repository also contains two substantial monitoring products: a cluster health dashboard and a GPU fleet manager. The graph emphasizes those runtime capabilities and their domain stages. Several links to unsampled subsystems are omitted where the excerpts and index do not establish a caller relationship.

Main entry points: [`cvs/monitors/metrics_exp/server/fleet_manager/main.py`](https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/fleet_manager/main.py) (Fleet manager API), [`cvs/runners/_base_runner.py`](https://github.com/rocm/cvs/blob/main/cvs/runners/_base_runner.py) (Suite runner), [`cvs/core/orchestrators/container.py`](https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/container.py) (Container orchestration), [`cvs/core/orchestrators/baremetal.py`](https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/baremetal.py) (Cluster orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and inputs"]
  node_cvs_cli["CVS CLI<br/>[main.py]"]
  node_cli_plugins["CLI commands"]
  node_config_generation["Config generation"]
end

subgraph group_runtime["Validation runtime"]
  node_runner["Suite runner<br/>[_base_runner.py]"]
  node_aorta_runner["Aorta runner<br/>[aorta.py]"]
  node_orchestrator["Cluster orchestration<br/>[baremetal.py]"]
  node_container_orch["Container orchestration<br/>[container.py]"]
  node_scheduler["Host scheduler<br/>[scheduler.py]"]
  node_docker_runtime["Docker runtime<br/>[docker.py]"]
  node_ssh_exec["SSH execution"]
end

subgraph group_workloads["Workload suites"]
  node_training["Training suites"]
  node_inference["Inference suites"]
  node_vllm_job["vLLM benchmark<br/>[vllm_job.py]"]
  node_model_query["Model endpoint checks<br/>[model_query_lib.py]"]
  node_report_payload["Inference reports"]
end

subgraph group_cluster_monitor["Cluster monitor"]
  node_cluster_ui["Cluster dashboard<br/>[App.tsx]"]
  node_cluster_api["Monitor API<br/>[main.py]"]
  node_collectors["Health collectors"]
  node_ssh_manager["Monitor SSH manager<br/>[ssh_manager.py]"]
  node_go_collector["Go collector<br/>[go_collector.py]"]
end

subgraph group_fleet["GPU fleet manager"]
  node_fleet_ui["Fleet manager UI<br/>[App.tsx]"]
  node_fleet_api["Fleet manager API<br/>[main.py]"]
  node_fleet_routes["Fleet API routes"]
  node_fleet_db[("Fleet database<br/>[database.py]")]
  node_fleet_services["Fleet services"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cvs_cli
node_cvs_cli -->|"discovers and dispatches"| node_cli_plugins
node_cli_plugins -->|"generates configs"| node_config_generation
node_operator -.->|"runs suites"| node_runner
node_aorta_runner -->|"uses base runner"| node_runner
node_aorta_runner -->|"uses runtime"| node_docker_runtime
node_orchestrator -->|"uses"| node_scheduler
node_container_orch -->|"reuses"| node_orchestrator
node_container_orch -->|"uses"| node_scheduler
node_container_orch -->|"selects runtime"| node_docker_runtime
node_orchestrator -.->|"executes remotely"| node_ssh_exec
node_runner -.->|"runs workloads"| node_training
node_runner -.->|"runs workloads"| node_inference
node_inference -.->|"includes job"| node_vllm_job
node_vllm_job -.->|"checks served model"| node_model_query
node_inference -->|"builds report payload"| node_report_payload
node_cluster_ui -.->|"requests monitor data"| node_cluster_api
node_cluster_api -->|"configures collectors"| node_collectors
node_cluster_api -->|"creates manager"| node_ssh_manager
node_ssh_manager -->|"delegates execution"| node_go_collector
node_fleet_ui -.->|"uses API"| node_fleet_api
node_fleet_api -->|"registers routes"| node_fleet_routes
node_fleet_api -->|"queries database"| node_fleet_db
node_fleet_api -->|"uses services"| node_fleet_services

click node_cvs_cli "https://github.com/rocm/cvs/blob/main/cvs/main.py"
click node_cli_plugins "https://github.com/rocm/cvs/tree/main/cvs/cli_plugins"
click node_config_generation "https://github.com/rocm/cvs/tree/main/cvs/input/generate"
click node_runner "https://github.com/rocm/cvs/blob/main/cvs/runners/_base_runner.py"
click node_aorta_runner "https://github.com/rocm/cvs/blob/main/cvs/runners/aorta.py"
click node_orchestrator "https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/baremetal.py"
click node_container_orch "https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/container.py"
click node_scheduler "https://github.com/rocm/cvs/blob/main/cvs/core/scheduler.py"
click node_docker_runtime "https://github.com/rocm/cvs/blob/main/cvs/core/runtimes/docker.py"
click node_ssh_exec "https://github.com/rocm/cvs/blob/main/cvs/lib/parallel_ssh_lib.py"
click node_training "https://github.com/rocm/cvs/tree/main/cvs/lib/training"
click node_inference "https://github.com/rocm/cvs/tree/main/cvs/lib/inference"
click node_vllm_job "https://github.com/rocm/cvs/blob/main/cvs/lib/inference/vllm_job.py"
click node_model_query "https://github.com/rocm/cvs/blob/main/cvs/lib/utils/model_query_lib.py"
click node_report_payload "https://github.com/rocm/cvs/blob/main/cvs/lib/report/inference_payload.py"
click node_cluster_ui "https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/frontend/src/App.tsx"
click node_cluster_api "https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/main.py"
click node_collectors "https://github.com/rocm/cvs/tree/main/cvs/monitors/cluster-mon/backend/app/collectors"
click node_ssh_manager "https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/core/ssh_manager.py"
click node_go_collector "https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/core/go_collector.py"
click node_fleet_ui "https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/ui/src/App.tsx"
click node_fleet_api "https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/fleet_manager/main.py"
click node_fleet_routes "https://github.com/rocm/cvs/tree/main/cvs/monitors/metrics_exp/server/fleet_manager/api/routes"
click node_fleet_db "https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/fleet_manager/models/database.py"
click node_fleet_services "https://github.com/rocm/cvs/tree/main/cvs/monitors/metrics_exp/server/fleet_manager/services"

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_cvs_cli,node_cli_plugins,node_config_generation toneBlue
class node_runner,node_aorta_runner,node_orchestrator,node_container_orch,node_scheduler,node_docker_runtime,node_ssh_exec toneAmber
class node_training,node_inference,node_vllm_job,node_model_query,node_report_payload toneMint
class node_cluster_ui,node_cluster_api,node_collectors,node_ssh_manager,node_go_collector toneRose
class node_fleet_ui,node_fleet_api,node_fleet_routes,node_fleet_db,node_fleet_services,node_operator toneIndigo
```

## Components

### CLI and inputs

- [CVS CLI](https://github.com/rocm/cvs/blob/main/cvs/main.py): `cvs/main.py`
- [CLI commands](https://github.com/rocm/cvs/tree/main/cvs/cli_plugins): `cvs/cli_plugins`
- [Config generation](https://github.com/rocm/cvs/tree/main/cvs/input/generate): `cvs/input/generate`

### Validation runtime

- [Suite runner](https://github.com/rocm/cvs/blob/main/cvs/runners/_base_runner.py): `cvs/runners/_base_runner.py`
- [Aorta runner](https://github.com/rocm/cvs/blob/main/cvs/runners/aorta.py): `cvs/runners/aorta.py`
- [Cluster orchestration](https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/baremetal.py): `cvs/core/orchestrators/baremetal.py`
- [Container orchestration](https://github.com/rocm/cvs/blob/main/cvs/core/orchestrators/container.py): `cvs/core/orchestrators/container.py`
- [Host scheduler](https://github.com/rocm/cvs/blob/main/cvs/core/scheduler.py): `cvs/core/scheduler.py`
- [Docker runtime](https://github.com/rocm/cvs/blob/main/cvs/core/runtimes/docker.py): `cvs/core/runtimes/docker.py`
- [SSH execution](https://github.com/rocm/cvs/blob/main/cvs/lib/parallel_ssh_lib.py): `cvs/lib/parallel_ssh_lib.py`

### Workload suites

- [Training suites](https://github.com/rocm/cvs/tree/main/cvs/lib/training): `cvs/lib/training`
- [Inference suites](https://github.com/rocm/cvs/tree/main/cvs/lib/inference): `cvs/lib/inference`
- [vLLM benchmark](https://github.com/rocm/cvs/blob/main/cvs/lib/inference/vllm_job.py): `cvs/lib/inference/vllm_job.py`
- [Model endpoint checks](https://github.com/rocm/cvs/blob/main/cvs/lib/utils/model_query_lib.py): `cvs/lib/utils/model_query_lib.py`
- [Inference reports](https://github.com/rocm/cvs/blob/main/cvs/lib/report/inference_payload.py): `cvs/lib/report/inference_payload.py`

### Cluster monitor

- [Cluster dashboard](https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/frontend/src/App.tsx): `cvs/monitors/cluster-mon/frontend/src/App.tsx`
- [Monitor API](https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/main.py): `cvs/monitors/cluster-mon/backend/app/main.py`
- [Health collectors](https://github.com/rocm/cvs/tree/main/cvs/monitors/cluster-mon/backend/app/collectors): `cvs/monitors/cluster-mon/backend/app/collectors`
- [Monitor SSH manager](https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/core/ssh_manager.py): `cvs/monitors/cluster-mon/backend/app/core/ssh_manager.py`
- [Go collector](https://github.com/rocm/cvs/blob/main/cvs/monitors/cluster-mon/backend/app/core/go_collector.py): `cvs/monitors/cluster-mon/backend/app/core/go_collector.py`

### GPU fleet manager

- [Fleet manager UI](https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/ui/src/App.tsx): `cvs/monitors/metrics_exp/server/ui/src/App.tsx`
- [Fleet manager API](https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/fleet_manager/main.py): `cvs/monitors/metrics_exp/server/fleet_manager/main.py`
- [Fleet API routes](https://github.com/rocm/cvs/tree/main/cvs/monitors/metrics_exp/server/fleet_manager/api/routes): `cvs/monitors/metrics_exp/server/fleet_manager/api/routes`
- [Fleet database](https://github.com/rocm/cvs/blob/main/cvs/monitors/metrics_exp/server/fleet_manager/models/database.py): `cvs/monitors/metrics_exp/server/fleet_manager/models/database.py`
- [Fleet services](https://github.com/rocm/cvs/tree/main/cvs/monitors/metrics_exp/server/fleet_manager/services): `cvs/monitors/metrics_exp/server/fleet_manager/services`

### Other components

- **Operator**

## Connections

- Operator → CVS CLI: invokes
- CVS CLI → CLI commands: discovers and dispatches (evidence: `cvs/main.py`)
- CLI commands → Config generation: generates configs (evidence: `cvs/input/generate/cluster_json.py`)
- Operator → Suite runner: runs suites
- Aorta runner → Suite runner: uses base runner (evidence: `cvs/runners/aorta.py`)
- Aorta runner → Docker runtime: uses runtime (evidence: `cvs/runners/aorta.py`)
- Cluster orchestration → Host scheduler: uses (evidence: `cvs/core/orchestrators/baremetal.py`)
- Container orchestration → Cluster orchestration: reuses (evidence: `cvs/core/orchestrators/container.py`)
- Container orchestration → Host scheduler: uses (evidence: `cvs/core/orchestrators/container.py`)
- Container orchestration → Docker runtime: selects runtime (evidence: `cvs/core/orchestrators/container.py`)
- Cluster orchestration → SSH execution: executes remotely
- Suite runner → Training suites: runs workloads
- Suite runner → Inference suites: runs workloads
- Inference suites → vLLM benchmark: includes job (evidence: `cvs/lib/inference/vllm_job.py`)
- vLLM benchmark → Model endpoint checks: checks served model (evidence: `cvs/lib/inference/vllm_job.py`)
- Inference suites → Inference reports: builds report payload (evidence: `cvs/lib/report/inference_payload.py`)
- Cluster dashboard → Monitor API: requests monitor data
- Monitor API → Health collectors: configures collectors (evidence: `cvs/monitors/cluster-mon/backend/app/main.py`)
- Monitor API → Monitor SSH manager: creates manager (evidence: `cvs/monitors/cluster-mon/backend/app/main.py`)
- Monitor SSH manager → Go collector: delegates execution (evidence: `cvs/monitors/cluster-mon/backend/app/core/ssh_manager.py`)
- Fleet manager UI → Fleet manager API: uses API
- Fleet manager API → Fleet API routes: registers routes (evidence: `cvs/monitors/metrics_exp/server/fleet_manager/main.py`)
- Fleet manager API → Fleet database: queries database (evidence: `cvs/monitors/metrics_exp/server/fleet_manager/main.py`)
- Fleet manager API → Fleet services: uses services (evidence: `cvs/monitors/metrics_exp/server/fleet_manager/main.py`)
