# 1catai/1catqa architecture

> Architecture diagram of the GitHub repository 1catai/1catqa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1catai/1catqa
- Repository: https://github.com/1catai/1catqa

## Overview

1Cat-V100-QA is a V100-focused GPU qualification suite. Users start a run through the CLI, terminal UI, or HTTP API; the orchestrator discovers GPUs, captures baseline health, runs NVLink/P2P and gpu-burn checks, compares post-run counters and temperature outcomes, then produces per-run reports. The README also documents remote result queries and webhook notifications. The graph reflects the sampled orchestration and interface code; some detailed test internals and API routes are described by the README rather than inspected source excerpts.

Main entry points: [`src/gpuqa/core.py`](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py) (Test orchestration), [`src/gpuqa/commands.py`](https://github.com/1catai/1catqa/blob/master/src/gpuqa/commands.py) (Command runner), [`src/gpuqa/httpd.py`](https://github.com/1catai/1catqa/blob/master/src/gpuqa/httpd.py) (HTTP API), [`src/gpuqa/reporting.py`](https://github.com/1catai/1catqa/blob/master/src/gpuqa/reporting.py) (Report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_desktop_entry["Desktop entry<br/>[gui_entry.py]"]
  node_tui["Terminal UI<br/>[tui.py]"]
  node_http["HTTP API<br/>[httpd.py]"]
end

subgraph group_testing["Qualification workflow"]
  node_orchestrator["Test orchestration<br/>[core.py]"]
  node_discovery["GPU discovery<br/>[core.py]"]
  node_baseline["Baseline health<br/>[core.py]"]
  node_link_test["NVLink P2P test<br/>[core.py]"]
  node_burn_test["GPU burn test<br/>[core.py]"]
  node_assessment["Result assessment<br/>[core.py]"]
  node_models["Run data models<br/>[models.py]"]
end

subgraph group_results["Results and reporting"]
  node_reporting["Report generation<br/>[reporting.py]"]
  node_result_files["Run report files"]
end

subgraph group_integrations["System integrations"]
  node_command_runner["Command runner<br/>[commands.py]"]
  node_nvidia["NVIDIA driver tools"]
  node_gpu_burn["gpu-burn"]
  node_p2p_tool["P2P benchmark"]
end

node_operator(("Operator"))
node_agent(("Remote agent"))
node_webhook["Webhook endpoint"]

node_operator -->|"runs commands"| node_cli
node_operator -->|"opens UI"| node_desktop_entry
node_desktop_entry -->|"starts"| node_tui
node_agent -->|"requests tests"| node_http
node_cli -->|"starts run"| node_orchestrator
node_tui -->|"starts run"| node_orchestrator
node_http -->|"starts run"| node_orchestrator
node_orchestrator -->|"discovers GPUs"| node_discovery
node_orchestrator -->|"captures baseline"| node_baseline
node_orchestrator -->|"runs link test"| node_link_test
node_orchestrator -->|"runs stress test"| node_burn_test
node_orchestrator -->|"evaluates outcomes"| node_assessment
node_orchestrator -->|"builds run data"| node_models
node_discovery -->|"queries devices"| node_command_runner
node_baseline -->|"samples counters"| node_command_runner
node_link_test -->|"runs benchmark"| node_command_runner
node_burn_test -->|"runs burn process"| node_command_runner
node_command_runner -->|"invokes queries"| node_nvidia
node_command_runner -->|"invokes stress test"| node_gpu_burn
node_command_runner -.->|"invokes benchmark"| node_p2p_tool
node_cli -->|"writes reports"| node_reporting
node_tui -->|"writes reports"| node_reporting
node_http -->|"writes reports"| node_reporting
node_reporting -->|"writes files"| node_result_files
node_http -.->|"posts completion"| node_webhook

click node_cli "https://github.com/1catai/1catqa/blob/master/src/gpuqa/cli.py"
click node_desktop_entry "https://github.com/1catai/1catqa/blob/master/src/gpuqa/gui_entry.py"
click node_tui "https://github.com/1catai/1catqa/blob/master/src/gpuqa/tui.py"
click node_http "https://github.com/1catai/1catqa/blob/master/src/gpuqa/httpd.py"
click node_orchestrator "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_discovery "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_baseline "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_link_test "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_burn_test "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_assessment "https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py"
click node_models "https://github.com/1catai/1catqa/blob/master/src/gpuqa/models.py"
click node_command_runner "https://github.com/1catai/1catqa/blob/master/src/gpuqa/commands.py"
click node_p2p_tool "https://github.com/1catai/1catqa/blob/master/cuda/p2p_bandwidth_matrix.cu"
click node_reporting "https://github.com/1catai/1catqa/blob/master/src/gpuqa/reporting.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_desktop_entry,node_tui,node_http toneBlue
class node_orchestrator,node_discovery,node_baseline,node_link_test,node_burn_test,node_assessment,node_models toneAmber
class node_reporting,node_result_files,node_webhook toneMint
class node_command_runner,node_nvidia,node_gpu_burn,node_p2p_tool toneRose
class node_operator,node_agent toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/1catai/1catqa/blob/master/src/gpuqa/cli.py): `src/gpuqa/cli.py`
- [Desktop entry](https://github.com/1catai/1catqa/blob/master/src/gpuqa/gui_entry.py): `src/gpuqa/gui_entry.py`
- [Terminal UI](https://github.com/1catai/1catqa/blob/master/src/gpuqa/tui.py): `src/gpuqa/tui.py`
- [HTTP API](https://github.com/1catai/1catqa/blob/master/src/gpuqa/httpd.py): `src/gpuqa/httpd.py`

### Qualification workflow

- [Test orchestration](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [GPU discovery](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [Baseline health](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [NVLink P2P test](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [GPU burn test](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [Result assessment](https://github.com/1catai/1catqa/blob/master/src/gpuqa/core.py): `src/gpuqa/core.py`
- [Run data models](https://github.com/1catai/1catqa/blob/master/src/gpuqa/models.py): `src/gpuqa/models.py`

### Results and reporting

- [Report generation](https://github.com/1catai/1catqa/blob/master/src/gpuqa/reporting.py): `src/gpuqa/reporting.py`
- **Run report files**

### System integrations

- [Command runner](https://github.com/1catai/1catqa/blob/master/src/gpuqa/commands.py): `src/gpuqa/commands.py`
- **NVIDIA driver tools**
- **gpu-burn**
- [P2P benchmark](https://github.com/1catai/1catqa/blob/master/cuda/p2p_bandwidth_matrix.cu): `cuda/p2p_bandwidth_matrix.cu`

### Other components

- **Operator**
- **Remote agent**
- **Webhook endpoint**

## Connections

- Operator → CLI commands: runs commands
- Operator → Desktop entry: opens UI
- Desktop entry → Terminal UI: starts
- Remote agent → HTTP API: requests tests
- CLI commands → Test orchestration: starts run
- Terminal UI → Test orchestration: starts run
- HTTP API → Test orchestration: starts run
- Test orchestration → GPU discovery: discovers GPUs
- Test orchestration → Baseline health: captures baseline
- Test orchestration → NVLink P2P test: runs link test
- Test orchestration → GPU burn test: runs stress test
- Test orchestration → Result assessment: evaluates outcomes
- Test orchestration → Run data models: builds run data
- GPU discovery → Command runner: queries devices
- Baseline health → Command runner: samples counters
- NVLink P2P test → Command runner: runs benchmark
- GPU burn test → Command runner: runs burn process
- Command runner → NVIDIA driver tools: invokes queries
- Command runner → gpu-burn: invokes stress test
- Command runner → P2P benchmark: invokes benchmark
- CLI commands → Report generation: writes reports
- Terminal UI → Report generation: writes reports
- HTTP API → Report generation: writes reports
- Report generation → Run report files: writes files
- HTTP API → Webhook endpoint: posts completion