# ldb0071/lemonmatrix architecture

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

- Interactive diagram: https://gitdiagram.com/ldb0071/lemonmatrix
- Repository: https://github.com/ldb0071/lemonmatrix

## Overview

LemonMatrix is a local benchmarking control plane for Lemonade server instances. Users discover or register an instance as a hardware/environment profile, select a benchmark, run trials through the Lemonade API, validate and save results, then inspect them locally or submit them to the public leaderboard. It also supports router-cost and Omni workflows, importing third-party results, and a local dashboard. The CLI, README, and selected modules establish these connections; several benchmark internals and dashboard routes were not sampled, so their internal call paths are not expanded.

Main entry points: [`src/lemonmatrix/cli.py`](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/cli.py) (CLI), [`src/lemonmatrix/sweep_batch.py`](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/sweep_batch.py) (Sweep batches), [`src/lemonmatrix/client.py`](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/client.py) (API client), [`src/lemonmatrix/webapp.py`](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/webapp.py) (Local dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_dashboard["Local dashboard<br/>[webapp.py]"]
end

subgraph group_profiles["Instance profiles"]
  node_discovery["Instance discovery<br/>[discover.py]"]
  node_profile["Profile management<br/>[profile.py]"]
  node_capabilities["Host capabilities<br/>[capabilities.py]"]
end

subgraph group_benchmarking["Benchmark execution"]
  node_client["API client<br/>[client.py]"]
  node_bench["Benchmark runs<br/>[bench.py]"]
  node_omni["Omni runs<br/>[omni.py]"]
  node_prompts["Prompt sets<br/>[prompt_sets.py]"]
  node_router_cost["Router cost<br/>[routing_cost.py]"]
  node_sweep_batch["Sweep batches<br/>[sweep_batch.py]"]
end

subgraph group_results["Results and exchange"]
  node_sweep_store[("Sweep state<br/>[sweep_store.py]")]
  node_results_store[("Result store<br/>[results_store.py]")]
  node_validation["Schema validation<br/>[validate.py]"]
  node_importers["Result import<br/>[importers.py]"]
  node_submission["Leaderboard submission<br/>[submit.py]"]
end

node_operator(("Operator"))
node_lemonade["Lemonade server"]

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses dashboard"| node_dashboard
node_cli -->|"detects instances"| node_discovery
node_cli -->|"manages profiles"| node_profile
node_profile -->|"queries server"| node_client
node_cli -->|"checks options"| node_capabilities
node_capabilities -->|"uses environment"| node_profile
node_cli -->|"runs benchmarks"| node_bench
node_cli -->|"runs Omni tasks"| node_omni
node_omni -->|"sends chat requests"| node_client
node_omni -.->|"uses task sets"| node_prompts
node_bench -.->|"sends benchmark requests"| node_client
node_cli -->|"calculates routing cost"| node_router_cost
node_cli -->|"starts sweeps"| node_sweep_batch
node_sweep_batch -->|"runs each configuration"| node_bench
node_sweep_batch -->|"uses server client"| node_client
node_sweep_batch -->|"validates results"| node_validation
node_sweep_batch -->|"saves trials"| node_results_store
node_dashboard -->|"launches sweeps"| node_sweep_batch
node_dashboard -->|"persists sweep state"| node_sweep_store
node_dashboard -.->|"reads results"| node_results_store
node_cli -.->|"lists and saves results"| node_results_store
node_cli -->|"validates submissions"| node_validation
node_cli -->|"imports external results"| node_importers
node_cli -->|"submits result files"| node_submission
node_client -->|"calls REST API"| node_lemonade
node_discovery -->|"probes liveness"| node_lemonade

click node_cli "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/cli.py"
click node_dashboard "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/webapp.py"
click node_discovery "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/discover.py"
click node_profile "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/profile.py"
click node_capabilities "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/capabilities.py"
click node_client "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/client.py"
click node_bench "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/bench.py"
click node_omni "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/omni.py"
click node_prompts "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/prompt_sets.py"
click node_router_cost "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/routing_cost.py"
click node_sweep_batch "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/sweep_batch.py"
click node_sweep_store "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/sweep_store.py"
click node_results_store "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/results_store.py"
click node_validation "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/validate.py"
click node_importers "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/importers.py"
click node_submission "https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/submit.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_dashboard toneBlue
class node_discovery,node_profile,node_capabilities toneAmber
class node_client,node_bench,node_omni,node_prompts,node_router_cost,node_sweep_batch,node_lemonade toneMint
class node_sweep_store,node_results_store,node_validation,node_importers,node_submission toneRose
class node_operator toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/cli.py): `src/lemonmatrix/cli.py`
- [Local dashboard](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/webapp.py): `src/lemonmatrix/webapp.py`

### Instance profiles

- [Instance discovery](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/discover.py): `src/lemonmatrix/discover.py`
- [Profile management](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/profile.py): `src/lemonmatrix/profile.py`
- [Host capabilities](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/capabilities.py): `src/lemonmatrix/capabilities.py`

### Benchmark execution

- [API client](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/client.py): `src/lemonmatrix/client.py`
- [Benchmark runs](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/bench.py): `src/lemonmatrix/bench.py`
- [Omni runs](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/omni.py): `src/lemonmatrix/omni.py`
- [Prompt sets](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/prompt_sets.py): `src/lemonmatrix/prompt_sets.py`
- [Router cost](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/routing_cost.py): `src/lemonmatrix/routing_cost.py`
- [Sweep batches](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/sweep_batch.py): `src/lemonmatrix/sweep_batch.py`

### Results and exchange

- [Sweep state](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/sweep_store.py): `src/lemonmatrix/sweep_store.py`
- [Result store](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/results_store.py): `src/lemonmatrix/results_store.py`
- [Schema validation](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/validate.py): `src/lemonmatrix/validate.py`
- [Result import](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/importers.py): `src/lemonmatrix/importers.py`
- [Leaderboard submission](https://github.com/ldb0071/lemonmatrix/blob/main/src/lemonmatrix/submit.py): `src/lemonmatrix/submit.py`

### Other components

- **Operator**
- **Lemonade server**

## Connections

- Operator → CLI: runs commands (evidence: `README.md`)
- Operator → Local dashboard: uses dashboard (evidence: `README.md`)
- CLI → Instance discovery: detects instances (evidence: `README.md`)
- CLI → Profile management: manages profiles (evidence: `README.md`)
- Profile management → API client: queries server (evidence: `src/lemonmatrix/profile.py`)
- CLI → Host capabilities: checks options (evidence: `src/lemonmatrix/cli.py`)
- Host capabilities → Profile management: uses environment (evidence: `src/lemonmatrix/capabilities.py`)
- CLI → Benchmark runs: runs benchmarks (evidence: `README.md`)
- CLI → Omni runs: runs Omni tasks (evidence: `README.md`)
- Omni runs → API client: sends chat requests (evidence: `src/lemonmatrix/omni.py`)
- Omni runs → Prompt sets: uses task sets
- Benchmark runs → API client: sends benchmark requests
- CLI → Router cost: calculates routing cost (evidence: `src/lemonmatrix/cli.py`)
- CLI → Sweep batches: starts sweeps (evidence: `src/lemonmatrix/cli.py`)
- Sweep batches → Benchmark runs: runs each configuration (evidence: `src/lemonmatrix/sweep_batch.py`)
- Sweep batches → API client: uses server client (evidence: `src/lemonmatrix/sweep_batch.py`)
- Sweep batches → Schema validation: validates results (evidence: `src/lemonmatrix/sweep_batch.py`)
- Sweep batches → Result store: saves trials (evidence: `src/lemonmatrix/sweep_batch.py`)
- Local dashboard → Sweep batches: launches sweeps (evidence: `src/lemonmatrix/webapp.py`)
- Local dashboard → Sweep state: persists sweep state (evidence: `src/lemonmatrix/webapp.py`)
- Local dashboard → Result store: reads results (evidence: `src/lemonmatrix/webapp.py`)
- CLI → Result store: lists and saves results (evidence: `src/lemonmatrix/cli.py`)
- CLI → Schema validation: validates submissions (evidence: `README.md`)
- CLI → Result import: imports external results (evidence: `README.md`)
- CLI → Leaderboard submission: submits result files (evidence: `README.md`)
- API client → Lemonade server: calls REST API (evidence: `src/lemonmatrix/client.py`)
- Instance discovery → Lemonade server: probes liveness (evidence: `src/lemonmatrix/discover.py`)
