# mizcausevic-dev/llm-cost-budget-operator architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/llm-cost-budget-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/llm-cost-budget-operator
- Repository: https://github.com/mizcausevic-dev/llm-cost-budget-operator

## Overview

Purpose and principal workflow: A cluster administrator creates an `LLMCostBudget` through the Kubernetes API, and the operator evaluates it against spend held in a referenced ConfigMap. A cost pipeline—documented as paired with `llm-cost-span-exporter`—writes the running total; the operator records budget posture in resource status and emits Warning events for warning or over-budget states.

Components

**Declarative budget API**
- **Budget author** — *null repository path*: creates budget resources specifying a monthly USD limit, warning threshold, and ConfigMap/key cost source.
- **LLMCostBudget resource contract** — `api/v1alpha1/llmcostbudget_types.go`: defines the spec, status, conditions, and reported budget states used by the operator and Kubernetes API.
- **Kubernetes API server** — *null repository path*: stores budget resources and ConfigMaps, serves reads and status updates, and exposes events.

**Operator runtime**
- **Manager entry point** — `cmd/main.go`: registers Kubernetes and budget types, creates the controller-runtime manager and event recorder, and registers the reconciler.
- **Budget reconciler** — `internal/controller/llmcostbudget_controller.go`: responds to budget and ConfigMap watches, reads source data, handles missing or invalid inputs, updates status, emits events, and schedules hourly requeues.

**Evaluation**
- **Budget evaluator** — `internal/budget/budget.go`: parses limit and observed spend, applies the default 80% warning threshold when unset, computes rounded percent used and state, and formats USD values.

**Spend input**
- **Cost pipeline** — *null repository path*: the documented external pipeline computes cost and writes the accumulated total to the ConfigMap referenced by a budget.

Relationships

- **Budget author -> Kubernetes API server**: creates an `LLMCostBudget`; the README describes declarative resources applied to the cluster.
- **Kubernetes API server -> Manager entry point**: supplies cluster configuration used by the manager; `cmd/main.go` obtains it through `ctrl.GetConfigOrDie()`.
- **Manager entry point -> Budget reconciler**: registers the reconciler and its budget and ConfigMap watches.
- **Budget reconciler -> Kubernetes API server**: watches and reads budget resources, and lists budgets in a ConfigMap’s namespace to map changes to reconcile requests.
- **Budget reconciler -> Kubernetes API server**: reads the referenced ConfigMap and its configured data key during reconciliation.
- **Cost pipeline -> Kubernetes API server**: writes accumulated spend to a ConfigMap; this is documented behavior, not shown in sampled source.
- **Budget reconciler -> Budget evaluator**: passes the budget spec and observed spend string to `Evaluate`.
- **Budget evaluator -> Budget reconciler**: returns the calculated spend, percent, and state; the reconciler formats results and builds status conditions.
- **Budget reconciler -> Kubernetes API server**: writes budget status, including spend, percent, state, and conditions.
- **Budget reconciler -> Kubernetes API server**: records Warning events for warning and over-budget states through its event recorder.
- **Kubernetes API server -> Budget reconciler**: a changed referenced ConfigMap is mapped to reconcile requests; the reconciler also requeues hourly as a safety net.

Coverage limits: The README documents the CRD, Helm installation, and exporter pairing, but their runtime installation details and the external cost-writing pipeline are not present in the sampled source. The precise event delivery and downstream alert-consumer path are not established.

Main entry points: [`internal/controller/llmcostbudget_controller.go`](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/controller/llmcostbudget_controller.go) (Budget Reconciler), [`cmd/main.go`](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/cmd/main.go) (Manager Entry Point), [`internal/budget/budget.go`](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/budget/budget.go) (Budget Evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_declarative_api["Declarative Budget API"]
  node_budget_author(("Budget Author<br/>actor"))
  node_budget_contract["LLMCostBudget Contract<br/>resource contract"]
  node_kubernetes_api["Kubernetes API Server<br/>platform"]
end

subgraph group_operator_runtime["Operator Runtime"]
  node_manager["Manager Entry Point<br/>runtime"]
  node_reconciler["Budget Reconciler<br/>controller"]
end

subgraph group_evaluation["Budget Evaluation"]
  node_evaluator["Budget Evaluator<br/>[budget.go]"]
end

subgraph group_spend_input["Spend Input"]
  node_cost_pipeline["Cost Pipeline<br/>external pipeline"]
end

node_budget_author -->|"creates budget"| node_kubernetes_api
node_kubernetes_api -->|"supplies config"| node_manager
node_manager -->|"registers"| node_reconciler
node_reconciler -->|"watches and reads"| node_kubernetes_api
node_reconciler -->|"reads ConfigMap"| node_kubernetes_api
node_cost_pipeline -->|"writes spend"| node_kubernetes_api
node_reconciler -->|"evaluates spend"| node_evaluator
node_evaluator -->|"returns results"| node_reconciler
node_reconciler -->|"updates status"| node_kubernetes_api
node_reconciler -->|"records events"| node_kubernetes_api
node_kubernetes_api -->|"triggers reconcile"| node_reconciler
node_reconciler -->|"requeues hourly"| node_reconciler

click node_budget_contract "https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/api/v1alpha1/llmcostbudget_types.go"
click node_manager "https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/cmd/main.go"
click node_reconciler "https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/controller/llmcostbudget_controller.go"
click node_evaluator "https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/budget/budget.go"

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_budget_author,node_budget_contract,node_kubernetes_api toneBlue
class node_manager,node_reconciler toneAmber
class node_evaluator toneMint
class node_cost_pipeline toneRose
```

## Components

### Declarative Budget API

- **Budget Author**: actor
- [LLMCostBudget Contract](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/api/v1alpha1/llmcostbudget_types.go): resource contract · `api/v1alpha1/llmcostbudget_types.go`
- **Kubernetes API Server**: platform

### Operator Runtime

- [Manager Entry Point](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/cmd/main.go): runtime · `cmd/main.go`
- [Budget Reconciler](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/controller/llmcostbudget_controller.go): controller · `internal/controller/llmcostbudget_controller.go`

### Budget Evaluation

- [Budget Evaluator](https://github.com/mizcausevic-dev/llm-cost-budget-operator/blob/main/internal/budget/budget.go): service · `internal/budget/budget.go`

### Spend Input

- **Cost Pipeline**: external pipeline

## Connections

- Budget Author → Kubernetes API Server: creates budget
- Kubernetes API Server → Manager Entry Point: supplies config
- Manager Entry Point → Budget Reconciler: registers
- Budget Reconciler → Kubernetes API Server: watches and reads · Watches budgets and lists budgets in a ConfigMap namespace to map changes to reconcile requests.
- Budget Reconciler → Kubernetes API Server: reads ConfigMap · Reads the referenced ConfigMap and configured data key.
- Cost Pipeline → Kubernetes API Server: writes spend · Writes accumulated spend to the referenced ConfigMap.
- Budget Reconciler → Budget Evaluator: evaluates spend · Passes the budget spec and observed spend string to Evaluate.
- Budget Evaluator → Budget Reconciler: returns results · Returns calculated spend, percent, and state.
- Budget Reconciler → Kubernetes API Server: updates status · Writes spend, percent, state, and conditions.
- Budget Reconciler → Kubernetes API Server: records events · Emits Warning events for warning and over-budget states.
- Kubernetes API Server → Budget Reconciler: triggers reconcile · Changed referenced ConfigMaps are mapped to reconcile requests.
- Budget Reconciler → Budget Reconciler: requeues hourly · Hourly requeue acts as a safety net.