# scarletkc/colab-playground architecture

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

- Interactive diagram: https://gitdiagram.com/scarletkc/colab-playground
- Repository: https://github.com/scarletkc/colab-playground

## Overview

Colab Playground is a desktop front end for the Google Colab CLI. A user configures accounts and session limits in the app, provisions a runtime, then monitors cost and can stop it, forward a port, or run a plugin. The graph keeps app state, core domain services, and host/CLI execution distinct. README claims establish the main capabilities; source-index references and excerpts support the internal links, but several UI and service implementations were not sampled in detail.

Main entry points: [`crates/core/src/backend.rs`](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/backend.rs) (Backend selection), [`crates/app/src/ui`](https://github.com/scarletkc/colab-playground/tree/main/crates/app/src/ui) (Desktop UI), [`crates/core/src/provision.rs`](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/provision.rs) (Session provisioning), [`crates/core/src/plugins.rs`](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/plugins.rs) (Plugin runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_ui["Desktop UI"]
  node_state["App state<br/>[mod.rs]"]
  node_preferences["Settings and languages<br/>[settings.rs]"]
end

subgraph group_domain["Colab workflows"]
  node_accounts["Account management<br/>[accounts.rs]"]
  node_provision["Session provisioning<br/>[provision.rs]"]
  node_ledger[("Session ledger<br/>[sessions.rs]")]
  node_guards["Cost guards<br/>[guard.rs]"]
  node_usage["Usage tracking<br/>[usage.rs]"]
  node_tunnels["Port forwarding<br/>[tunnel.rs]"]
  node_plugins["Plugin runtime<br/>[plugins.rs]"]
  node_model["GGUF model plugin<br/>[worker.py]"]
end

subgraph group_execution["Execution layer"]
  node_backend["Backend selection<br/>[backend.rs]"]
  node_cli["Colab CLI adapter<br/>[cli.rs]"]
  node_host["Host process runner<br/>[host.rs]"]
  node_paths["Data layout<br/>[paths.rs]"]
  node_updates["App updater<br/>[updater.rs]"]
end

subgraph group_integrations["External systems"]
  node_colab["Google Colab CLI"]
  node_runtime["Colab runtime"]
  node_network["HTTP services"]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_ui -->|"updates"| node_state
node_state -->|"dispatches calls"| node_backend
node_backend -->|"builds service"| node_accounts
node_backend -->|"builds service"| node_provision
node_backend -->|"builds service"| node_ledger
node_backend -->|"builds service"| node_guards
node_backend -->|"builds service"| node_usage
node_backend -->|"builds service"| node_tunnels
node_backend -->|"builds service"| node_plugins
node_backend -->|"builds service"| node_updates
node_cli -->|"runs commands"| node_host
node_host -->|"invokes"| node_colab
node_accounts -->|"uses layout"| node_paths
node_provision -->|"creates sessions"| node_cli
node_provision -->|"probes hardware"| node_runtime
node_guards -->|"enforces watchdog"| node_runtime
node_plugins -->|"runs scripts"| node_runtime
node_model -.->|"downloads models"| node_network
node_ui -->|"edits preferences"| node_preferences
node_ui -->|"forwards ports"| node_tunnels
node_ui -->|"manages plugins"| node_plugins
node_updates -->|"downloads releases"| node_network

click node_ui "https://github.com/scarletkc/colab-playground/tree/main/crates/app/src/ui"
click node_state "https://github.com/scarletkc/colab-playground/blob/main/crates/app/src/state/mod.rs"
click node_preferences "https://github.com/scarletkc/colab-playground/blob/main/crates/app/src/settings.rs"
click node_accounts "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/accounts.rs"
click node_provision "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/provision.rs"
click node_ledger "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/sessions.rs"
click node_guards "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/guard.rs"
click node_usage "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/usage.rs"
click node_tunnels "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/tunnel.rs"
click node_plugins "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/plugins.rs"
click node_model "https://github.com/scarletkc/colab-playground/blob/main/plugins/llama-cpp/worker.py"
click node_backend "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/backend.rs"
click node_cli "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/cli.rs"
click node_host "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/host.rs"
click node_paths "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/paths.rs"
click node_updates "https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/updater.rs"

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_ui,node_state,node_preferences,node_user toneBlue
class node_accounts,node_provision,node_ledger,node_guards,node_usage,node_tunnels,node_plugins,node_model toneAmber
class node_backend,node_cli,node_host,node_paths,node_updates toneMint
class node_colab,node_runtime,node_network toneRose
```

## Components

### Desktop app

- [Desktop UI](https://github.com/scarletkc/colab-playground/tree/main/crates/app/src/ui): `crates/app/src/ui`
- [App state](https://github.com/scarletkc/colab-playground/blob/main/crates/app/src/state/mod.rs): `crates/app/src/state/mod.rs`
- [Settings and languages](https://github.com/scarletkc/colab-playground/blob/main/crates/app/src/settings.rs): `crates/app/src/settings.rs`

### Colab workflows

- [Account management](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/accounts.rs): `crates/core/src/accounts.rs`
- [Session provisioning](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/provision.rs): `crates/core/src/provision.rs`
- [Session ledger](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/sessions.rs): `crates/core/src/sessions.rs`
- [Cost guards](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/guard.rs): `crates/core/src/guard.rs`
- [Usage tracking](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/usage.rs): `crates/core/src/usage.rs`
- [Port forwarding](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/tunnel.rs): `crates/core/src/tunnel.rs`
- [Plugin runtime](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/plugins.rs): `crates/core/src/plugins.rs`
- [GGUF model plugin](https://github.com/scarletkc/colab-playground/blob/main/plugins/llama-cpp/worker.py): `plugins/llama-cpp/worker.py`

### Execution layer

- [Backend selection](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/backend.rs): `crates/core/src/backend.rs`
- [Colab CLI adapter](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/cli.rs): `crates/core/src/cli.rs`
- [Host process runner](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/host.rs): `crates/core/src/host.rs`
- [Data layout](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/paths.rs): `crates/core/src/paths.rs`
- [App updater](https://github.com/scarletkc/colab-playground/blob/main/crates/core/src/updater.rs): `crates/core/src/updater.rs`

### External systems

- **Google Colab CLI**
- **Colab runtime**
- **HTTP services**

### Other components

- **User**

## Connections

- User → Desktop UI: uses (evidence: `README.md`)
- Desktop UI → App state: updates (evidence: `crates/app/src/state/mod.rs`)
- App state → Backend selection: dispatches calls (evidence: `crates/app/src/state/mod.rs`)
- Backend selection → Account management: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Session provisioning: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Session ledger: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Cost guards: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Usage tracking: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Port forwarding: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → Plugin runtime: builds service (evidence: `crates/core/src/backend.rs`)
- Backend selection → App updater: builds service (evidence: `crates/core/src/backend.rs`)
- Colab CLI adapter → Host process runner: runs commands (evidence: `crates/core/src/cli.rs`)
- Host process runner → Google Colab CLI: invokes (evidence: `crates/core/src/host.rs`)
- Account management → Data layout: uses layout (evidence: `crates/core/src/paths.rs`)
- Session provisioning → Colab CLI adapter: creates sessions (evidence: `crates/core/src/provision.rs`)
- Session provisioning → Colab runtime: probes hardware (evidence: `crates/core/src/provision.rs`)
- Cost guards → Colab runtime: enforces watchdog (evidence: `crates/core/src/guard.rs`)
- Plugin runtime → Colab runtime: runs scripts (evidence: `crates/core/src/plugins.rs`)
- GGUF model plugin → HTTP services: downloads models
- Desktop UI → Settings and languages: edits preferences (evidence: `README.md`)
- Desktop UI → Port forwarding: forwards ports (evidence: `README.md`)
- Desktop UI → Plugin runtime: manages plugins (evidence: `crates/app/src/ui/pages/plugins/mod.rs`)
- App updater → HTTP services: downloads releases
