# riiazz/devbox architecture

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

- Interactive diagram: https://gitdiagram.com/riiazz/devbox
- Repository: https://github.com/riiazz/devbox

## Overview

DevBox is a Rust CLI for creating reproducible, project-scoped development environments. The main workflow is to initialize or discover a workspace, load its configuration, then run programs or an interactive shell with isolated variables and a tool-aware PATH. A separate tool-install workflow resolves a release for the current target, downloads and verifies an archive, extracts it, and registers the executable. Services declared in configuration can be started and monitored, with state and logs exposed through CLI commands. Some subsystem links reflect README capabilities because their source was not sampled.

Main entry points: [`crates/cli/src/main.rs`](https://github.com/riiazz/devbox/blob/main/crates/cli/src/main.rs) (DevBox CLI), [`crates/downloader/src/installer.rs`](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/installer.rs) (Tool installer), [`crates/supervisor/src/supervisor.rs`](https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/supervisor.rs) (Supervisor), [`crates/runtime/src/runtime.rs`](https://github.com/riiazz/devbox/blob/main/crates/runtime/src/runtime.rs) (Process runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and config"]
  node_workspace_api["Workspace<br/>[workspace.rs]"]
  node_config["Project config<br/>[config.rs]"]
end

subgraph group_runtime["Environment runtime"]
  node_environment["Environment<br/>[environment.rs]"]
  node_isolation["Isolation paths<br/>[isolation.rs]"]
  node_runtime_exec["Process runtime<br/>[runtime.rs]"]
  node_process["Child processes<br/>[process.rs]"]
end

subgraph group_tools["Tool management"]
  node_installer["Tool installer<br/>[installer.rs]"]
  node_resolver["Release resolver<br/>[resolve.rs]"]
  node_target["Platform target<br/>[target.rs]"]
  node_download["Archive download<br/>[download.rs]"]
  node_checksum["Checksum verify<br/>[checksum.rs]"]
  node_extract["Archive extract<br/>[extract.rs]"]
  node_registry[("Tool registry<br/>[registry.rs]")]
end

subgraph group_services["Service supervision"]
  node_supervisor["Supervisor<br/>[supervisor.rs]"]
  node_state[("Process state<br/>[state.rs]")]
  node_dashboard["Live dashboard<br/>[dashboard.rs]"]
end

node_user(("Developer"))
node_cli["DevBox CLI<br/>[main.rs]"]
node_github{{"GitHub releases"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"discovers workspace"| node_workspace_api
node_cli -->|"loads config"| node_config
node_cli -->|"installs tools"| node_installer
node_installer -->|"resolves source"| node_resolver
node_resolver -->|"checks platform"| node_target
node_installer -->|"fetches archive"| node_download
node_download -->|"downloads from"| node_github
node_installer -->|"verifies archive"| node_checksum
node_installer -->|"extracts archive"| node_extract
node_installer -->|"registers tool"| node_registry
node_cli -->|"reads and updates"| node_registry
node_cli -->|"configures environment"| node_environment
node_cli -->|"applies isolation"| node_isolation
node_cli -->|"runs shell or command"| node_runtime_exec
node_runtime_exec -->|"applies variables"| node_environment
node_runtime_exec -->|"launches process"| node_process
node_cli -->|"manages services"| node_supervisor
node_supervisor -->|"uses service definitions"| node_config
node_supervisor -->|"passes environment"| node_environment
node_supervisor -->|"spawns services"| node_process
node_supervisor -->|"persists process state"| node_state
node_supervisor -->|"displays live status"| node_dashboard
node_cli -->|"reports service status"| node_state

click node_cli "https://github.com/riiazz/devbox/blob/main/crates/cli/src/main.rs"
click node_workspace_api "https://github.com/riiazz/devbox/blob/main/crates/workspace/src/workspace.rs"
click node_config "https://github.com/riiazz/devbox/blob/main/crates/config/src/config.rs"
click node_environment "https://github.com/riiazz/devbox/blob/main/crates/runtime/src/environment.rs"
click node_isolation "https://github.com/riiazz/devbox/blob/main/crates/runtime/src/isolation.rs"
click node_runtime_exec "https://github.com/riiazz/devbox/blob/main/crates/runtime/src/runtime.rs"
click node_process "https://github.com/riiazz/devbox/blob/main/crates/runtime/src/process.rs"
click node_installer "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/installer.rs"
click node_resolver "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/resolve.rs"
click node_target "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/target.rs"
click node_download "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/download.rs"
click node_checksum "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/checksum.rs"
click node_extract "https://github.com/riiazz/devbox/blob/main/crates/downloader/src/extract.rs"
click node_registry "https://github.com/riiazz/devbox/blob/main/crates/toolchain/src/registry.rs"
click node_supervisor "https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/supervisor.rs"
click node_state "https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/state.rs"
click node_dashboard "https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/dashboard.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_workspace_api,node_config toneBlue
class node_environment,node_isolation,node_runtime_exec,node_process toneAmber
class node_installer,node_resolver,node_target,node_download,node_checksum,node_extract,node_registry toneMint
class node_supervisor,node_state,node_dashboard toneRose
class node_user,node_github toneIndigo
class node_cli toneTeal
```

## Components

### Workspace and config

- [Workspace](https://github.com/riiazz/devbox/blob/main/crates/workspace/src/workspace.rs): `crates/workspace/src/workspace.rs`
- [Project config](https://github.com/riiazz/devbox/blob/main/crates/config/src/config.rs): `crates/config/src/config.rs`

### Environment runtime

- [Environment](https://github.com/riiazz/devbox/blob/main/crates/runtime/src/environment.rs): `crates/runtime/src/environment.rs`
- [Isolation paths](https://github.com/riiazz/devbox/blob/main/crates/runtime/src/isolation.rs): `crates/runtime/src/isolation.rs`
- [Process runtime](https://github.com/riiazz/devbox/blob/main/crates/runtime/src/runtime.rs): `crates/runtime/src/runtime.rs`
- [Child processes](https://github.com/riiazz/devbox/blob/main/crates/runtime/src/process.rs): `crates/runtime/src/process.rs`

### Tool management

- [Tool installer](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/installer.rs): `crates/downloader/src/installer.rs`
- [Release resolver](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/resolve.rs): `crates/downloader/src/resolve.rs`
- [Platform target](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/target.rs): `crates/downloader/src/target.rs`
- [Archive download](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/download.rs): `crates/downloader/src/download.rs`
- [Checksum verify](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/checksum.rs): `crates/downloader/src/checksum.rs`
- [Archive extract](https://github.com/riiazz/devbox/blob/main/crates/downloader/src/extract.rs): `crates/downloader/src/extract.rs`
- [Tool registry](https://github.com/riiazz/devbox/blob/main/crates/toolchain/src/registry.rs): `crates/toolchain/src/registry.rs`

### Service supervision

- [Supervisor](https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/supervisor.rs): `crates/supervisor/src/supervisor.rs`
- [Process state](https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/state.rs): `crates/supervisor/src/state.rs`
- [Live dashboard](https://github.com/riiazz/devbox/blob/main/crates/supervisor/src/dashboard.rs): `crates/supervisor/src/dashboard.rs`

### Other components

- **Developer**
- [DevBox CLI](https://github.com/riiazz/devbox/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- **GitHub releases**

## Connections

- Developer → DevBox CLI: runs commands
- DevBox CLI → Workspace: discovers workspace
- DevBox CLI → Project config: loads config
- DevBox CLI → Tool installer: installs tools
- Tool installer → Release resolver: resolves source
- Release resolver → Platform target: checks platform
- Tool installer → Archive download: fetches archive
- Archive download → GitHub releases: downloads from
- Tool installer → Checksum verify: verifies archive
- Tool installer → Archive extract: extracts archive
- Tool installer → Tool registry: registers tool
- DevBox CLI → Tool registry: reads and updates
- DevBox CLI → Environment: configures environment
- DevBox CLI → Isolation paths: applies isolation
- DevBox CLI → Process runtime: runs shell or command
- Process runtime → Environment: applies variables
- Process runtime → Child processes: launches process
- DevBox CLI → Supervisor: manages services
- Supervisor → Project config: uses service definitions
- Supervisor → Environment: passes environment
- Supervisor → Child processes: spawns services
- Supervisor → Process state: persists process state
- Supervisor → Live dashboard: displays live status
- DevBox CLI → Process state: reports service status