# hec-ovi/llama-vulkan-strix architecture

> Architecture diagram of the GitHub repository hec-ovi/llama-vulkan-strix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hec-ovi/llama-vulkan-strix
- Repository: https://github.com/hec-ovi/llama-vulkan-strix

## Overview

This repository packages llama.cpp inference for AMD Strix Halo rather than implementing a model server. The main workflow is to configure model paths and context in `.env`, select a Compose package, start the chosen stack, and send requests to its API. Documented branches include stock Vulkan, ROCmFP4+MTP, and Laguna ROCmFPX; supporting tools validate context, inspect GTT placement, and benchmark served models. The Compose files and custom entrypoint were not sampled, so their internal wiring is represented only where the README documents it.

Main entry points: [`.env.example`](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/.env.example) (Model settings), [`docker-compose.laguna-rocmfpx.yml`](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.laguna-rocmfpx.yml) (Laguna ROCmFPX), [`scripts/bench_server.py`](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_server.py) (Depth benchmark), [`scripts/bench_full.py`](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_full.py) (Full benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Inference deployment"]
  node_env["Model settings<br/>[.env.example]"]
  node_stock["Vulkan stack<br/>[docker-compose.yml]"]
  node_model_packages["Model packages"]
  node_fp4["ROCmFP4 stack"]
  node_laguna_fpx["Laguna ROCmFPX"]
  node_laguna_entry["Laguna entrypoint"]
end

subgraph group_operations["Runtime operations"]
  node_context_check["Context validator"]
  node_gpu_mem["GPU memory report<br/>[gpu_mem.py]"]
  node_gtt_verify["GTT verification<br/>[verify-gtt.sh]"]
end

subgraph group_measurement["Performance measurement"]
  node_bench_server["Depth benchmark<br/>[bench_server.py]"]
  node_bench_full["Full benchmark<br/>[bench_full.py]"]
  node_bench_results["Benchmark results"]
end

node_operator(("Operator"))
node_server["llama.cpp server"]
node_api_user(("API client"))

node_operator -->|"sets options"| node_env
node_operator -->|"selects package"| node_model_packages
node_env -->|"configures"| node_stock
node_model_packages -->|"extends stack"| node_stock
node_env -->|"configures"| node_fp4
node_env -->|"configures"| node_laguna_fpx
node_laguna_fpx -.->|"uses entrypoint"| node_laguna_entry
node_stock -->|"starts server"| node_server
node_fp4 -->|"starts server"| node_server
node_laguna_fpx -->|"starts server"| node_server
node_api_user -->|"sends requests"| node_server
node_operator -->|"validates settings"| node_context_check
node_operator -->|"checks memory"| node_gpu_mem
node_operator -->|"verifies placement"| node_gtt_verify
node_operator -->|"runs benchmark"| node_bench_server
node_bench_server -->|"requests completion"| node_server
node_operator -->|"runs benchmark"| node_bench_full
node_bench_full -->|"requests completion"| node_server
node_bench_server -.->|"records metrics"| node_bench_results
node_bench_full -.->|"records metrics"| node_bench_results

click node_env "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/.env.example"
click node_stock "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.yml"
click node_model_packages "https://github.com/hec-ovi/llama-vulkan-strix/tree/main/compose/models"
click node_fp4 "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.rocmfp4.yml"
click node_laguna_fpx "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.laguna-rocmfpx.yml"
click node_laguna_entry "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/tools/entrypoint.laguna-rocmfpx.sh"
click node_context_check "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/check_context_config.py"
click node_gpu_mem "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/gpu_mem.py"
click node_gtt_verify "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/verify-gtt.sh"
click node_bench_server "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_server.py"
click node_bench_full "https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_full.py"
click node_bench_results "https://github.com/hec-ovi/llama-vulkan-strix/tree/main/docs/bench-results"

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_env,node_stock,node_model_packages,node_fp4,node_laguna_fpx,node_laguna_entry,node_api_user toneBlue
class node_context_check,node_gpu_mem,node_gtt_verify toneAmber
class node_bench_server,node_bench_full,node_bench_results,node_server toneMint
class node_operator toneIndigo
```

## Components

### Inference deployment

- [Model settings](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/.env.example): `.env.example`
- [Vulkan stack](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.yml): `docker-compose.yml`
- [Model packages](https://github.com/hec-ovi/llama-vulkan-strix/tree/main/compose/models): `compose/models`
- [ROCmFP4 stack](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.rocmfp4.yml): `docker-compose.rocmfp4.yml`
- [Laguna ROCmFPX](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/docker-compose.laguna-rocmfpx.yml): `docker-compose.laguna-rocmfpx.yml`
- [Laguna entrypoint](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/tools/entrypoint.laguna-rocmfpx.sh): `tools/entrypoint.laguna-rocmfpx.sh`

### Runtime operations

- [Context validator](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/check_context_config.py): `scripts/check_context_config.py`
- [GPU memory report](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/gpu_mem.py): `scripts/gpu_mem.py`
- [GTT verification](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/verify-gtt.sh): `scripts/verify-gtt.sh`

### Performance measurement

- [Depth benchmark](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_server.py): `scripts/bench_server.py`
- [Full benchmark](https://github.com/hec-ovi/llama-vulkan-strix/blob/main/scripts/bench_full.py): `scripts/bench_full.py`
- [Benchmark results](https://github.com/hec-ovi/llama-vulkan-strix/tree/main/docs/bench-results): `docs/bench-results`

### Other components

- **Operator**
- **llama.cpp server**
- **API client**

## Connections

- Operator → Model settings: sets options (evidence: `README.md`)
- Operator → Model packages: selects package (evidence: `README.md`)
- Model settings → Vulkan stack: configures (evidence: `README.md`)
- Model packages → Vulkan stack: extends stack (evidence: `README.md`)
- Model settings → ROCmFP4 stack: configures (evidence: `README.md`)
- Model settings → Laguna ROCmFPX: configures (evidence: `README.md`)
- Laguna ROCmFPX → Laguna entrypoint: uses entrypoint
- Vulkan stack → llama.cpp server: starts server (evidence: `README.md`)
- ROCmFP4 stack → llama.cpp server: starts server (evidence: `README.md`)
- Laguna ROCmFPX → llama.cpp server: starts server (evidence: `README.md`)
- API client → llama.cpp server: sends requests (evidence: `README.md`)
- Operator → Context validator: validates settings (evidence: `README.md`)
- Operator → GPU memory report: checks memory (evidence: `README.md`)
- Operator → GTT verification: verifies placement (evidence: `README.md`)
- Operator → Depth benchmark: runs benchmark (evidence: `scripts/bench_server.py`)
- Depth benchmark → llama.cpp server: requests completion (evidence: `scripts/bench_server.py`)
- Operator → Full benchmark: runs benchmark (evidence: `scripts/bench_full.py`)
- Full benchmark → llama.cpp server: requests completion (evidence: `scripts/bench_full.py`)
- Depth benchmark → Benchmark results: records metrics
- Full benchmark → Benchmark results: records metrics
