# bacnh85/yardmaster architecture

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

- Interactive diagram: https://gitdiagram.com/bacnh85/yardmaster
- Repository: https://github.com/bacnh85/yardmaster

## Overview

yardmaster is a self-hosted LLM proxy for coding-agent clients. The main flow accepts a client request, authenticates and routes it across configured upstream providers, optionally translates wire formats, streams the response, and records usage for the embedded dashboard. The dashboard also manages providers, combos, keys, quotas, and settings. Relationships reflect README statements and source-index references; some handler-level details and unsampled modules cannot be verified from the excerpts, so uncertain links are omitted.

Main entry points: [`web/src/App.tsx`](https://github.com/bacnh85/yardmaster/blob/main/web/src/App.tsx) (Dashboard shell), [`web/src/api.ts`](https://github.com/bacnh85/yardmaster/blob/main/web/src/api.ts) (Admin API client), [`internal/proxy/proxy.go`](https://github.com/bacnh85/yardmaster/blob/main/internal/proxy/proxy.go) (Request proxy), [`internal/server/server.go`](https://github.com/bacnh85/yardmaster/blob/main/internal/server/server.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Proxy runtime"]
  node_entry["CLI runtime<br/>[main.go]"]
  node_configuration["Configuration<br/>[config.go]"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_proxy["Request proxy<br/>[proxy.go]"]
  node_translation["Wire translation<br/>[translate.go]"]
end

subgraph group_providers["Provider and auth"]
  node_provider_registry["Provider registry<br/>[registry.go]"]
  node_cooldowns["Provider cooldowns<br/>[cooldowns.go]"]
  node_oauth["OAuth pool<br/>[oauth.go]"]
  node_auth["Inbound auth<br/>[auth.go]"]
end

subgraph group_observability["Usage and catalog"]
  node_store[("SQLite request store<br/>[store.go]")]
  node_catalog["Model catalog<br/>[catalog.go]"]
  node_quota["Quota reporting<br/>[quota.go]"]
end

subgraph group_dashboard["Admin dashboard"]
  node_dashboard_app["Dashboard shell<br/>[App.tsx]"]
  node_api_client["Admin API client<br/>[api.ts]"]
  node_analytics_ui["Stats views<br/>[UsageTab.tsx]"]
  node_request_ui["Request history<br/>[RequestsTab.tsx]"]
  node_live_ui["Live status<br/>[LiveTab.tsx]"]
  node_cache_ui["Cache statistics<br/>[CacheTab.tsx]"]
  node_latency_ui["Latency view<br/>[LatencyTab.tsx]"]
end

subgraph group_management["Dashboard management"]
  node_provider_ui["Provider manager<br/>[ProvidersTab.tsx]"]
  node_combo_ui["Combo manager<br/>[CombosTab.tsx]"]
  node_endpoint_ui["Endpoint keys<br/>[EndpointsTab.tsx]"]
  node_model_ui["Models and tests<br/>[ModelsTab.tsx]"]
  node_playground["Request playground<br/>[Playground.tsx]"]
  node_settings_ui["Settings<br/>[SettingsTab.tsx]"]
  node_quota_ui["Quota view<br/>[QuotaTab.tsx]"]
end

node_agents(("Coding agents"))
node_upstreams(("LLM providers"))

node_agents -->|"send requests"| node_http_server
node_entry -->|"loads config"| node_configuration
node_entry -->|"registers providers"| node_provider_registry
node_entry -->|"constructs proxy"| node_proxy
node_entry -->|"starts server"| node_http_server
node_entry -->|"opens store"| node_store
node_http_server -->|"routes requests"| node_proxy
node_http_server -->|"reads request data"| node_store
node_http_server -->|"serves catalog"| node_catalog
node_http_server -->|"serves quotas"| node_quota
node_proxy -->|"selects providers"| node_provider_registry
node_proxy -->|"translates wires"| node_translation
node_proxy -->|"records usage"| node_store
node_proxy -->|"checks inbound keys"| node_auth
node_proxy -->|"gets provider tokens"| node_oauth
node_proxy -->|"uses cooldowns"| node_cooldowns
node_provider_registry -->|"loads provider settings"| node_configuration
node_provider_registry -->|"uses auth adapters"| node_auth
node_oauth -->|"persists tokens"| node_store
node_proxy -->|"dispatches requests"| node_upstreams
node_dashboard_app -->|"calls admin API"| node_api_client
node_dashboard_app -->|"renders tab"| node_analytics_ui
node_dashboard_app -->|"renders tab"| node_request_ui
node_dashboard_app -->|"renders tab"| node_live_ui
node_dashboard_app -->|"renders tab"| node_cache_ui
node_dashboard_app -->|"renders tab"| node_latency_ui
node_dashboard_app -->|"renders tab"| node_provider_ui
node_dashboard_app -->|"renders tab"| node_combo_ui
node_dashboard_app -->|"renders tab"| node_endpoint_ui
node_dashboard_app -->|"renders tab"| node_model_ui
node_dashboard_app -->|"renders tab"| node_settings_ui
node_dashboard_app -->|"renders tab"| node_quota_ui
node_provider_ui -->|"opens test view"| node_playground
node_model_ui -->|"uses test view"| node_playground
node_analytics_ui -->|"fetches stats"| node_api_client
node_provider_ui -->|"manages providers"| node_api_client
node_combo_ui -->|"manages combos"| node_api_client
node_endpoint_ui -->|"manages keys"| node_api_client
node_model_ui -->|"loads models"| node_api_client
node_playground -->|"sends test request"| node_api_client
node_quota_ui -->|"fetches quotas"| node_api_client
node_request_ui -->|"fetches history"| node_api_client
node_cache_ui -->|"fetches cache stats"| node_api_client
node_latency_ui -->|"fetches latency"| node_api_client
node_live_ui -->|"fetches live data"| node_api_client
node_api_client -->|"calls admin endpoints"| node_http_server

click node_entry "https://github.com/bacnh85/yardmaster/blob/main/cmd/yardmaster/main.go"
click node_configuration "https://github.com/bacnh85/yardmaster/blob/main/internal/config/config.go"
click node_http_server "https://github.com/bacnh85/yardmaster/blob/main/internal/server/server.go"
click node_proxy "https://github.com/bacnh85/yardmaster/blob/main/internal/proxy/proxy.go"
click node_translation "https://github.com/bacnh85/yardmaster/blob/main/internal/translate/translate.go"
click node_provider_registry "https://github.com/bacnh85/yardmaster/blob/main/internal/provider/registry.go"
click node_cooldowns "https://github.com/bacnh85/yardmaster/blob/main/internal/provider/cooldowns.go"
click node_oauth "https://github.com/bacnh85/yardmaster/blob/main/internal/auth/oauth.go"
click node_auth "https://github.com/bacnh85/yardmaster/blob/main/internal/auth/auth.go"
click node_store "https://github.com/bacnh85/yardmaster/blob/main/internal/store/store.go"
click node_catalog "https://github.com/bacnh85/yardmaster/blob/main/internal/server/catalog.go"
click node_quota "https://github.com/bacnh85/yardmaster/blob/main/internal/server/quota.go"
click node_dashboard_app "https://github.com/bacnh85/yardmaster/blob/main/web/src/App.tsx"
click node_api_client "https://github.com/bacnh85/yardmaster/blob/main/web/src/api.ts"
click node_analytics_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/UsageTab.tsx"
click node_provider_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/ProvidersTab.tsx"
click node_combo_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/CombosTab.tsx"
click node_endpoint_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/EndpointsTab.tsx"
click node_model_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/ModelsTab.tsx"
click node_playground "https://github.com/bacnh85/yardmaster/blob/main/web/src/Playground.tsx"
click node_settings_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/SettingsTab.tsx"
click node_quota_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/QuotaTab.tsx"
click node_request_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/RequestsTab.tsx"
click node_live_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/LiveTab.tsx"
click node_cache_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/CacheTab.tsx"
click node_latency_ui "https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/LatencyTab.tsx"

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_entry,node_configuration,node_http_server,node_proxy,node_translation toneBlue
class node_provider_registry,node_cooldowns,node_oauth,node_auth toneAmber
class node_store,node_catalog,node_quota toneMint
class node_dashboard_app,node_api_client,node_analytics_ui,node_request_ui,node_live_ui,node_cache_ui,node_latency_ui toneRose
class node_provider_ui,node_combo_ui,node_endpoint_ui,node_model_ui,node_playground,node_settings_ui,node_quota_ui,node_agents,node_upstreams toneIndigo
```

## Components

### Proxy runtime

- [CLI runtime](https://github.com/bacnh85/yardmaster/blob/main/cmd/yardmaster/main.go): `cmd/yardmaster/main.go`
- [Configuration](https://github.com/bacnh85/yardmaster/blob/main/internal/config/config.go): `internal/config/config.go`
- [HTTP server](https://github.com/bacnh85/yardmaster/blob/main/internal/server/server.go): `internal/server/server.go`
- [Request proxy](https://github.com/bacnh85/yardmaster/blob/main/internal/proxy/proxy.go): `internal/proxy/proxy.go`
- [Wire translation](https://github.com/bacnh85/yardmaster/blob/main/internal/translate/translate.go): `internal/translate/translate.go`

### Provider and auth

- [Provider registry](https://github.com/bacnh85/yardmaster/blob/main/internal/provider/registry.go): `internal/provider/registry.go`
- [Provider cooldowns](https://github.com/bacnh85/yardmaster/blob/main/internal/provider/cooldowns.go): `internal/provider/cooldowns.go`
- [OAuth pool](https://github.com/bacnh85/yardmaster/blob/main/internal/auth/oauth.go): `internal/auth/oauth.go`
- [Inbound auth](https://github.com/bacnh85/yardmaster/blob/main/internal/auth/auth.go): `internal/auth/auth.go`

### Usage and catalog

- [SQLite request store](https://github.com/bacnh85/yardmaster/blob/main/internal/store/store.go): `internal/store/store.go`
- [Model catalog](https://github.com/bacnh85/yardmaster/blob/main/internal/server/catalog.go): `internal/server/catalog.go`
- [Quota reporting](https://github.com/bacnh85/yardmaster/blob/main/internal/server/quota.go): `internal/server/quota.go`

### Admin dashboard

- [Dashboard shell](https://github.com/bacnh85/yardmaster/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Admin API client](https://github.com/bacnh85/yardmaster/blob/main/web/src/api.ts): `web/src/api.ts`
- [Stats views](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/UsageTab.tsx): `web/src/tabs/UsageTab.tsx`
- [Request history](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/RequestsTab.tsx): `web/src/tabs/RequestsTab.tsx`
- [Live status](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/LiveTab.tsx): `web/src/tabs/LiveTab.tsx`
- [Cache statistics](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/CacheTab.tsx): `web/src/tabs/CacheTab.tsx`
- [Latency view](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/LatencyTab.tsx): `web/src/tabs/LatencyTab.tsx`

### Dashboard management

- [Provider manager](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/ProvidersTab.tsx): `web/src/tabs/ProvidersTab.tsx`
- [Combo manager](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/CombosTab.tsx): `web/src/tabs/CombosTab.tsx`
- [Endpoint keys](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/EndpointsTab.tsx): `web/src/tabs/EndpointsTab.tsx`
- [Models and tests](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/ModelsTab.tsx): `web/src/tabs/ModelsTab.tsx`
- [Request playground](https://github.com/bacnh85/yardmaster/blob/main/web/src/Playground.tsx): `web/src/Playground.tsx`
- [Settings](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/SettingsTab.tsx): `web/src/tabs/SettingsTab.tsx`
- [Quota view](https://github.com/bacnh85/yardmaster/blob/main/web/src/tabs/QuotaTab.tsx): `web/src/tabs/QuotaTab.tsx`

### Other components

- **Coding agents**
- **LLM providers**

## Connections

- Coding agents → HTTP server: send requests
- CLI runtime → Configuration: loads config (evidence: `cmd/yardmaster/main.go`)
- CLI runtime → Provider registry: registers providers (evidence: `cmd/yardmaster/main.go`)
- CLI runtime → Request proxy: constructs proxy (evidence: `cmd/yardmaster/main.go`)
- CLI runtime → HTTP server: starts server (evidence: `cmd/yardmaster/main.go`)
- CLI runtime → SQLite request store: opens store (evidence: `cmd/yardmaster/main.go`)
- HTTP server → Request proxy: routes requests (evidence: `internal/server/server.go`)
- HTTP server → SQLite request store: reads request data (evidence: `internal/server/server.go`)
- HTTP server → Model catalog: serves catalog (evidence: `internal/server/server.go`)
- HTTP server → Quota reporting: serves quotas
- Request proxy → Provider registry: selects providers (evidence: `internal/proxy/proxy.go`)
- Request proxy → Wire translation: translates wires (evidence: `internal/proxy/proxy.go`)
- Request proxy → SQLite request store: records usage (evidence: `internal/proxy/proxy.go`)
- Request proxy → Inbound auth: checks inbound keys (evidence: `internal/proxy/proxy.go`)
- Request proxy → OAuth pool: gets provider tokens (evidence: `internal/proxy/proxy.go`)
- Request proxy → Provider cooldowns: uses cooldowns (evidence: `internal/proxy/proxy.go`)
- Provider registry → Configuration: loads provider settings (evidence: `internal/provider/registry.go`)
- Provider registry → Inbound auth: uses auth adapters (evidence: `internal/provider/registry.go`)
- OAuth pool → SQLite request store: persists tokens (evidence: `internal/auth/oauth.go`)
- Request proxy → LLM providers: dispatches requests
- Dashboard shell → Admin API client: calls admin API (evidence: `web/src/App.tsx`)
- Dashboard shell → Stats views: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Request history: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Live status: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Cache statistics: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Latency view: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Provider manager: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Combo manager: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Endpoint keys: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Models and tests: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Settings: renders tab (evidence: `web/src/App.tsx`)
- Dashboard shell → Quota view: renders tab (evidence: `web/src/App.tsx`)
- Provider manager → Request playground: opens test view (evidence: `web/src/tabs/ProvidersTab.tsx`)
- Models and tests → Request playground: uses test view (evidence: `web/src/tabs/ModelsTab.tsx`)
- Stats views → Admin API client: fetches stats (evidence: `web/src/tabs/UsageTab.tsx`)
- Provider manager → Admin API client: manages providers (evidence: `web/src/tabs/ProvidersTab.tsx`)
- Combo manager → Admin API client: manages combos (evidence: `web/src/tabs/CombosTab.tsx`)
- Endpoint keys → Admin API client: manages keys (evidence: `web/src/tabs/EndpointsTab.tsx`)
- Models and tests → Admin API client: loads models (evidence: `web/src/tabs/ModelsTab.tsx`)
- Request playground → Admin API client: sends test request (evidence: `web/src/Playground.tsx`)
- Quota view → Admin API client: fetches quotas (evidence: `web/src/tabs/QuotaTab.tsx`)
- Request history → Admin API client: fetches history (evidence: `web/src/tabs/RequestsTab.tsx`)
- Cache statistics → Admin API client: fetches cache stats (evidence: `web/src/tabs/CacheTab.tsx`)
- Latency view → Admin API client: fetches latency (evidence: `web/src/tabs/LatencyTab.tsx`)
- Live status → Admin API client: fetches live data (evidence: `web/src/tabs/LiveTab.tsx`)
- Admin API client → HTTP server: calls admin endpoints
