# vizuaraai/capstone-gpu-economics-engine architecture

> Architecture diagram of the GitHub repository vizuaraai/capstone-gpu-economics-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vizuaraai/capstone-gpu-economics-engine
- Repository: https://github.com/vizuaraai/capstone-gpu-economics-engine

## Overview

GPU Economics Engine predicts inference throughput and token cost from GPU/model specifications, measures the same serving points with vLLM, then compares results and recommends the cheapest GPU meeting latency targets. The graph preserves the model’s roofline, MoE, and FLOPs-only branches alongside the measurement and validation stages. Relationships for the harness flow rely on README documentation; unsampled harness details are not inferred.

Main entry points: [`src/gpu_econ/specs.py`](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/specs.py) (Typed specs), [`src/gpu_econ/cli.py`](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/cli.py) (CLI commands), [`src/gpu_econ/predict.py`](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/predict.py) (Bandwidth model), [`src/gpu_econ/records.py`](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/records.py) (Run records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Prediction model"]
  node_specs["Typed specs<br/>[specs.py]"]
  node_gpu_data["GPU specs<br/>[gpus.yaml]"]
  node_model_data["Model specs<br/>[models.yaml]"]
  node_price_data["GPU prices<br/>[prices.yaml]"]
  node_roofline["Roofline analysis<br/>[roofline.py]"]
  node_moe["MoE dispersion<br/>[moe.py]"]
  node_predict["Bandwidth model<br/>[predict.py]"]
  node_naive["FLOPs baseline<br/>[naive.py]"]
  node_slo["SLO recommender<br/>[slo.py]"]
end

subgraph group_measurement["Measurement harness"]
  node_serve["vLLM server<br/>[serve.py]"]
  node_benchmark["Serving benchmark<br/>[bench.py]"]
  node_sweep["Measurement sweep<br/>[sweep.py]"]
  node_measure["Record normalizer<br/>[measure.py]"]
end

subgraph group_validation["Records and validation"]
  node_records[("Run records<br/>[records.py]")]
  node_predicted["Predicted records<br/>[.gitkeep]"]
  node_measured["Measured records<br/>[.gitkeep]"]
  node_compare["Record comparison<br/>[compare.py]"]
  node_report["Validation report<br/>[report.py]"]
end

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

node_operator(("Engineer"))
node_vllm["vLLM tooling"]
node_gpu["GPU hardware"]

node_operator -->|"runs commands"| node_cli
node_gpu_data -->|"loaded as specs"| node_specs
node_model_data -->|"loaded as specs"| node_specs
node_price_data -->|"loaded as specs"| node_specs
node_specs -->|"provides GPU specs"| node_roofline
node_specs -->|"provides model specs"| node_moe
node_specs -->|"provides inputs"| node_predict
node_moe -->|"models dispersion"| node_predict
node_specs -->|"provides inputs"| node_naive
node_predict -->|"computes comparison"| node_naive
node_predict -->|"supplies decode estimates"| node_slo
node_specs -->|"provides candidates"| node_slo
node_cli -->|"dispatches prediction"| node_predict
node_cli -->|"dispatches baseline"| node_naive
node_cli -->|"dispatches recommendation"| node_slo
node_predict -->|"creates records"| node_records
node_cli -->|"saves predictions"| node_records
node_records -->|"writes records"| node_predicted
node_operator -->|"starts measurement"| node_serve
node_serve -->|"launches server"| node_vllm
node_serve -->|"runs on hardware"| node_gpu
node_operator -->|"runs benchmark"| node_benchmark
node_benchmark -->|"drives benchmark"| node_vllm
node_serve -->|"serves workload"| node_benchmark
node_benchmark -->|"produces benchmark JSON"| node_measure
node_measure -->|"normalizes results"| node_records
node_measure -->|"writes records"| node_measured
node_operator -->|"runs sweep"| node_sweep
node_cli -->|"dispatches validation"| node_compare
node_predicted -->|"joins predictions"| node_compare
node_measured -->|"joins measurements"| node_compare
node_records -->|"loads records"| node_compare
node_compare -->|"provides comparison"| node_report
node_cli -->|"writes report"| node_report

click node_cli "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/cli.py"
click node_specs "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/specs.py"
click node_gpu_data "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/gpus.yaml"
click node_model_data "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/models.yaml"
click node_price_data "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/prices.yaml"
click node_roofline "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/roofline.py"
click node_moe "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/moe.py"
click node_predict "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/predict.py"
click node_naive "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/naive.py"
click node_slo "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/slo.py"
click node_serve "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/serve.py"
click node_benchmark "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/bench.py"
click node_sweep "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/sweep.py"
click node_measure "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/measure.py"
click node_records "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/records.py"
click node_predicted "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/results/predicted/.gitkeep"
click node_measured "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/results/measured/.gitkeep"
click node_compare "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/validate/compare.py"
click node_report "https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/validate/report.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_specs,node_gpu_data,node_model_data,node_price_data,node_roofline,node_moe,node_predict,node_naive,node_slo toneBlue
class node_serve,node_benchmark,node_sweep,node_measure toneAmber
class node_records,node_predicted,node_measured,node_compare,node_report toneMint
class node_cli toneRose
class node_operator,node_vllm,node_gpu toneIndigo
```

## Components

### Prediction model

- [Typed specs](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/specs.py): `src/gpu_econ/specs.py`
- [GPU specs](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/gpus.yaml): `data/gpus.yaml`
- [Model specs](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/models.yaml): `data/models.yaml`
- [GPU prices](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/data/prices.yaml): `data/prices.yaml`
- [Roofline analysis](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/roofline.py): `src/gpu_econ/roofline.py`
- [MoE dispersion](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/moe.py): `src/gpu_econ/moe.py`
- [Bandwidth model](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/predict.py): `src/gpu_econ/predict.py`
- [FLOPs baseline](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/naive.py): `src/gpu_econ/naive.py`
- [SLO recommender](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/slo.py): `src/gpu_econ/slo.py`

### Measurement harness

- [vLLM server](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/serve.py): `harness/serve.py`
- [Serving benchmark](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/bench.py): `harness/bench.py`
- [Measurement sweep](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/sweep.py): `harness/sweep.py`
- [Record normalizer](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/harness/measure.py): `harness/measure.py`

### Records and validation

- [Run records](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/records.py): `src/gpu_econ/records.py`
- [Predicted records](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/results/predicted/.gitkeep): `results/predicted/.gitkeep`
- [Measured records](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/results/measured/.gitkeep): `results/measured/.gitkeep`
- [Record comparison](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/validate/compare.py): `validate/compare.py`
- [Validation report](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/validate/report.py): `validate/report.py`

### User interface

- [CLI commands](https://github.com/vizuaraai/capstone-gpu-economics-engine/blob/main/src/gpu_econ/cli.py): `src/gpu_econ/cli.py`

### Other components

- **Engineer**
- **vLLM tooling**
- **GPU hardware**

## Connections

- Engineer → CLI commands: runs commands (evidence: `README.md`)
- GPU specs → Typed specs: loaded as specs (evidence: `src/gpu_econ/specs.py`)
- Model specs → Typed specs: loaded as specs (evidence: `src/gpu_econ/specs.py`)
- GPU prices → Typed specs: loaded as specs (evidence: `src/gpu_econ/specs.py`)
- Typed specs → Roofline analysis: provides GPU specs (evidence: `src/gpu_econ/roofline.py`)
- Typed specs → MoE dispersion: provides model specs (evidence: `src/gpu_econ/moe.py`)
- Typed specs → Bandwidth model: provides inputs (evidence: `src/gpu_econ/predict.py`)
- MoE dispersion → Bandwidth model: models dispersion (evidence: `src/gpu_econ/predict.py`)
- Typed specs → FLOPs baseline: provides inputs (evidence: `src/gpu_econ/naive.py`)
- Bandwidth model → FLOPs baseline: computes comparison (evidence: `src/gpu_econ/naive.py`)
- Bandwidth model → SLO recommender: supplies decode estimates (evidence: `src/gpu_econ/slo.py`)
- Typed specs → SLO recommender: provides candidates (evidence: `src/gpu_econ/slo.py`)
- CLI commands → Bandwidth model: dispatches prediction (evidence: `src/gpu_econ/cli.py`)
- CLI commands → FLOPs baseline: dispatches baseline (evidence: `src/gpu_econ/cli.py`)
- CLI commands → SLO recommender: dispatches recommendation (evidence: `src/gpu_econ/cli.py`)
- Bandwidth model → Run records: creates records (evidence: `README.md`)
- CLI commands → Run records: saves predictions (evidence: `README.md`)
- Run records → Predicted records: writes records (evidence: `src/gpu_econ/records.py`)
- Engineer → vLLM server: starts measurement (evidence: `README.md`)
- vLLM server → vLLM tooling: launches server (evidence: `README.md`)
- vLLM server → GPU hardware: runs on hardware (evidence: `README.md`)
- Engineer → Serving benchmark: runs benchmark (evidence: `README.md`)
- Serving benchmark → vLLM tooling: drives benchmark (evidence: `README.md`)
- vLLM server → Serving benchmark: serves workload (evidence: `README.md`)
- Serving benchmark → Record normalizer: produces benchmark JSON (evidence: `README.md`)
- Record normalizer → Run records: normalizes results (evidence: `harness/measure.py`)
- Record normalizer → Measured records: writes records (evidence: `harness/measure.py`)
- Engineer → Measurement sweep: runs sweep (evidence: `README.md`)
- CLI commands → Record comparison: dispatches validation (evidence: `src/gpu_econ/cli.py`)
- Predicted records → Record comparison: joins predictions (evidence: `README.md`)
- Measured records → Record comparison: joins measurements (evidence: `README.md`)
- Run records → Record comparison: loads records (evidence: `validate/compare.py`)
- Record comparison → Validation report: provides comparison (evidence: `validate/report.py`)
- CLI commands → Validation report: writes report (evidence: `src/gpu_econ/cli.py`)
