# snowops-oss/snowopslabs architecture

> Architecture diagram of the GitHub repository snowops-oss/snowopslabs, 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/snowops-oss/snowopslabs
- Repository: https://github.com/snowops-oss/snowopslabs

## Overview

SnowOps Labs is a Kubernetes operations simulator. Engineers use `labctl` or the browser UI to provision a real platform, activate scenarios or inject incidents, then verify fixes against the live cluster; results, learning paths, timed challenges, traffic exercises, and app/provider comparison extend that workflow. The graph includes the CLI, runtime and domain engines, HTTP/UI boundary, and key user-facing capabilities. Some domain wiring is documented only at a high level, so uncertain links are dashed rather than asserted as inspected calls.

Main entry points: [`src/cmd/labctl/main.go`](https://github.com/snowops-oss/snowopslabs/blob/main/src/cmd/labctl/main.go) (labctl CLI), [`src/internal/httpapi/server.go`](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/httpapi/server.go) (HTTP API), [`src/internal/scenario/engine.go`](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/scenario/engine.go) (Scenario engine), [`src/ui/src/main.tsx`](https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/main.tsx) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["labctl CLI<br/>[main.go]"]
  node_browser["Browser UI<br/>[main.tsx]"]
end

subgraph group_operations["Lab operations"]
  node_runtime["Cluster runtimes<br/>[manager.go]"]
  node_platform["Platform providers<br/>[registry.go]"]
  node_workloads["Workload apps<br/>[workload.go]"]
  node_scenario["Scenario engine<br/>[engine.go]"]
  node_incident["Incident engine<br/>[incident.go]"]
  node_traffic["Traffic exercises<br/>[traffic.go]"]
end

subgraph group_learning["Practice and assessment"]
  node_checks["Live checks<br/>[runner.go]"]
  node_learningpaths["Learning paths<br/>[learn.go]"]
  node_challenges["Timed challenges<br/>[challenge.go]"]
  node_compare["Provider comparison<br/>[compare.go]"]
end

subgraph group_interface["API and interface"]
  node_api["HTTP API<br/>[server.go]"]
  node_views["Product views<br/>[Scenarios.tsx]"]
  node_api_client["UI API client<br/>[client.ts]"]
  node_query["Query cache<br/>[queryClient.ts]"]
end

subgraph group_state["State and results"]
  node_runs["Run execution<br/>[engine.go]"]
  node_store[("Persistent state<br/>[store.go]")]
  node_results["Results and leaderboard<br/>[results.go]"]
end

node_operator(("Engineer"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"operates lab"| node_browser
node_browser -->|"renders routes"| node_views
node_browser -.->|"requests data"| node_api_client
node_views -->|"calls endpoints"| node_api_client
node_views -.->|"reads cached data"| node_query
node_api_client -.->|"sends HTTP requests"| node_api
node_cli -->|"provisions clusters"| node_runtime
node_cli -->|"builds platform"| node_platform
node_cli -->|"activates scenarios"| node_scenario
node_cli -->|"injects faults"| node_incident
node_scenario -->|"grades work"| node_checks
node_scenario -->|"binds workload"| node_workloads
node_cli -.->|"drives traffic"| node_traffic
node_cli -.->|"runs curriculum"| node_learningpaths
node_cli -.->|"runs challenges"| node_challenges
node_cli -.->|"compares providers"| node_compare
node_api -.->|"serves operations"| node_scenario
node_api -.->|"serves operations"| node_incident
node_api -.->|"dispatches actions"| node_runs
node_runs -.->|"persists run state"| node_store
node_results -.->|"reads outcomes"| node_store

click node_cli "https://github.com/snowops-oss/snowopslabs/blob/main/src/cmd/labctl/main.go"
click node_browser "https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/main.tsx"
click node_runtime "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/runtime/manager.go"
click node_platform "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/platform/registry.go"
click node_workloads "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/workload/workload.go"
click node_scenario "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/scenario/engine.go"
click node_incident "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/incident/incident.go"
click node_traffic "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/traffic/traffic.go"
click node_checks "https://github.com/snowops-oss/snowopslabs/blob/main/src/pkg/checks/runner.go"
click node_learningpaths "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/learn/learn.go"
click node_challenges "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/challenge/challenge.go"
click node_compare "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/compare/compare.go"
click node_api "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/httpapi/server.go"
click node_views "https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/views/Scenarios.tsx"
click node_api_client "https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/api/client.ts"
click node_query "https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/lib/queryClient.ts"
click node_runs "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/run/engine.go"
click node_store "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/store/store.go"
click node_results "https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/results/results.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_cli,node_browser toneBlue
class node_runtime,node_platform,node_workloads,node_scenario,node_incident,node_traffic toneAmber
class node_checks,node_learningpaths,node_challenges,node_compare toneMint
class node_api,node_views,node_api_client,node_query toneRose
class node_runs,node_store,node_results,node_operator toneIndigo
```

## Components

### Entry points

- [labctl CLI](https://github.com/snowops-oss/snowopslabs/blob/main/src/cmd/labctl/main.go): `src/cmd/labctl/main.go`
- [Browser UI](https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/main.tsx): `src/ui/src/main.tsx`

### Lab operations

- [Cluster runtimes](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/runtime/manager.go): `src/internal/runtime/manager.go`
- [Platform providers](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/platform/registry.go): `src/internal/platform/registry.go`
- [Workload apps](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/workload/workload.go): `src/internal/workload/workload.go`
- [Scenario engine](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/scenario/engine.go): `src/internal/scenario/engine.go`
- [Incident engine](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/incident/incident.go): `src/internal/incident/incident.go`
- [Traffic exercises](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/traffic/traffic.go): `src/internal/traffic/traffic.go`

### Practice and assessment

- [Live checks](https://github.com/snowops-oss/snowopslabs/blob/main/src/pkg/checks/runner.go): `src/pkg/checks/runner.go`
- [Learning paths](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/learn/learn.go): `src/internal/learn/learn.go`
- [Timed challenges](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/challenge/challenge.go): `src/internal/challenge/challenge.go`
- [Provider comparison](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/compare/compare.go): `src/internal/compare/compare.go`

### API and interface

- [HTTP API](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/httpapi/server.go): `src/internal/httpapi/server.go`
- [Product views](https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/views/Scenarios.tsx): `src/ui/src/views/Scenarios.tsx`
- [UI API client](https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/api/client.ts): `src/ui/src/api/client.ts`
- [Query cache](https://github.com/snowops-oss/snowopslabs/blob/main/src/ui/src/lib/queryClient.ts): `src/ui/src/lib/queryClient.ts`

### State and results

- [Run execution](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/run/engine.go): `src/internal/run/engine.go`
- [Persistent state](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/store/store.go): `src/internal/store/store.go`
- [Results and leaderboard](https://github.com/snowops-oss/snowopslabs/blob/main/src/internal/results/results.go): `src/internal/results/results.go`

### Other components

- **Engineer**

## Connections

- Engineer → labctl CLI: runs commands (evidence: `README.md`)
- Engineer → Browser UI: operates lab (evidence: `README.md`)
- Browser UI → Product views: renders routes
- Browser UI → UI API client: requests data
- Product views → UI API client: calls endpoints
- Product views → Query cache: reads cached data
- UI API client → HTTP API: sends HTTP requests
- labctl CLI → Cluster runtimes: provisions clusters (evidence: `README.md`)
- labctl CLI → Platform providers: builds platform (evidence: `README.md`)
- labctl CLI → Scenario engine: activates scenarios (evidence: `README.md`)
- labctl CLI → Incident engine: injects faults (evidence: `README.md`)
- Scenario engine → Live checks: grades work (evidence: `src/internal/scenario/engine.go`)
- Scenario engine → Workload apps: binds workload (evidence: `src/internal/scenario/engine.go`)
- labctl CLI → Traffic exercises: drives traffic
- labctl CLI → Learning paths: runs curriculum
- labctl CLI → Timed challenges: runs challenges
- labctl CLI → Provider comparison: compares providers
- HTTP API → Scenario engine: serves operations
- HTTP API → Incident engine: serves operations
- HTTP API → Run execution: dispatches actions
- Run execution → Persistent state: persists run state
- Results and leaderboard → Persistent state: reads outcomes
