# swualabs/sandboxd-o architecture

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

- Interactive diagram: https://gitdiagram.com/swualabs/sandboxd-o
- Repository: https://github.com/swualabs/sandboxd-o

## Overview

sandboxd-o combines an administrator’s AWS cluster/worker provisioning, a control-plane API and scheduler, a node-local sandbox runtime, and a user CLI. The main workflow is sandbox request → orchestrator scheduling/reconciliation → node-agent provisioning through Containerd CRI, with sandbox state and networking managed locally. Admin provisioning also registers nodes and external endpoints with the control plane. The README documents networking, state reconciliation, resource management, and CLI capabilities; some subsystem wiring is unsampled, so those links are omitted or marked unverified.

Main entry points: [`sandboxd-orch/service/sandbox_ops.go`](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/service/sandbox_ops.go) (Orchestration Service), [`sandboxd-let/sandbox/service.go`](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/sandbox/service.go) (Sandbox Service), [`sandboxd-adm/orchestrate/worker.go`](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/orchestrate/worker.go) (Worker Operations), [`sandboxd-orch/http/handlers/handler.go`](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/http/handlers/handler.go) (Orchestrator API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["AWS Administration"]
  node_admin_cli["Admin CLI<br/>[main.go]"]
  node_admin_commands["Cluster Operations<br/>[cluster.go]"]
  node_worker_ops["Worker Operations<br/>[worker.go]"]
  node_aws["AWS Resources"]
  node_cluster_store[("Cluster Store<br/>[dynamodb.go]")]
end

subgraph group_control["Orchestrator Control Plane"]
  node_orch_api["Orchestrator API<br/>[handler.go]"]
  node_orch_service["Orchestration Service<br/>[sandbox_ops.go]"]
  node_node_ops["Node Operations<br/>[node_ops.go]"]
  node_repositories[("SQLite Repositories<br/>[node_repo.go]")]
  node_resource_cache["Resource Cache<br/>[resource_cache.go]"]
  node_orchestrator["Orchestrator Process<br/>[main.go]"]
end

subgraph group_runtime["Node Runtime"]
  node_node_agent_api["Node Agent API<br/>[handlers.go]"]
  node_sandbox_service["Sandbox Service<br/>[service.go]"]
  node_sandbox_state[("Sandbox State<br/>[file_store.go]")]
  node_networking["Sandbox Networking<br/>[firewall.go]"]
  node_validation["Spec Validation<br/>[validate.go]"]
end

subgraph group_clients["User Interfaces"]
  node_ctl["Sandbox CLI<br/>[main.go]"]
  node_ctl_commands["Resource Commands<br/>[resource_cmds.go]"]
end

node_operator(("Operator"))
node_cri["Containerd CRI"]
node_worker["Worker Node"]

node_operator -.->|"runs"| node_admin_cli
node_admin_cli -.->|"invokes"| node_admin_commands
node_admin_commands -.->|"provisions"| node_aws
node_admin_commands -.->|"persists cluster"| node_cluster_store
node_worker_ops -->|"provisions worker"| node_aws
node_worker_ops -->|"persists worker"| node_cluster_store
node_worker_ops -->|"registers node"| node_orch_api
node_worker_ops -.->|"installs agent"| node_worker
node_operator -.->|"runs"| node_ctl
node_ctl -.->|"dispatches"| node_ctl_commands
node_ctl_commands -.->|"requests API"| node_orch_api
node_orchestrator -->|"starts loops"| node_orch_service
node_orchestrator -->|"serves routes"| node_orch_api
node_orch_api -->|"calls"| node_orch_service
node_orch_service -.->|"reads and writes"| node_repositories
node_orch_service -.->|"uses resources"| node_resource_cache
node_orch_service -.->|"proxies node requests"| node_node_agent_api
node_orch_service -.->|"schedules sandboxes"| node_worker
node_node_agent_api -.->|"calls"| node_sandbox_service
node_sandbox_service -->|"creates containers"| node_cri
node_sandbox_service -->|"saves state"| node_sandbox_state
node_sandbox_service -->|"applies policy"| node_networking
node_sandbox_service -->|"validates IDs"| node_validation

click node_admin_cli "https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxadm/main.go"
click node_admin_commands "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/orchestrate/cluster.go"
click node_worker_ops "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/orchestrate/worker.go"
click node_aws "https://github.com/swualabs/sandboxd-o/tree/main/sandboxd-adm/awsx"
click node_cluster_store "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/store/dynamodb.go"
click node_orch_api "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/http/handlers/handler.go"
click node_orch_service "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/service/sandbox_ops.go"
click node_node_ops "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/service/node_ops.go"
click node_repositories "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/repo/node_repo.go"
click node_resource_cache "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/cache/resource_cache.go"
click node_node_agent_api "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/http/handlers.go"
click node_sandbox_service "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/sandbox/service.go"
click node_sandbox_state "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/store/file_store.go"
click node_networking "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/network/firewall.go"
click node_validation "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/model/validate.go"
click node_ctl "https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxctl/main.go"
click node_ctl_commands "https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-ctl/cmd/resource_cmds.go"
click node_orchestrator "https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxorch/main.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_admin_cli,node_admin_commands,node_worker_ops,node_aws,node_cluster_store toneBlue
class node_orch_api,node_orch_service,node_node_ops,node_repositories,node_resource_cache,node_orchestrator toneAmber
class node_node_agent_api,node_sandbox_service,node_sandbox_state,node_networking,node_validation toneMint
class node_ctl,node_ctl_commands,node_worker toneRose
class node_operator,node_cri toneIndigo
```

## Components

### AWS Administration

- [Admin CLI](https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxadm/main.go): `cmd/sbxadm/main.go`
- [Cluster Operations](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/orchestrate/cluster.go): `sandboxd-adm/orchestrate/cluster.go`
- [Worker Operations](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/orchestrate/worker.go): `sandboxd-adm/orchestrate/worker.go`
- [AWS Resources](https://github.com/swualabs/sandboxd-o/tree/main/sandboxd-adm/awsx): `sandboxd-adm/awsx`
- [Cluster Store](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-adm/store/dynamodb.go): `sandboxd-adm/store/dynamodb.go`

### Orchestrator Control Plane

- [Orchestrator API](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/http/handlers/handler.go): `sandboxd-orch/http/handlers/handler.go`
- [Orchestration Service](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/service/sandbox_ops.go): `sandboxd-orch/service/sandbox_ops.go`
- [Node Operations](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/service/node_ops.go): `sandboxd-orch/service/node_ops.go`
- [SQLite Repositories](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/repo/node_repo.go): `sandboxd-orch/repo/node_repo.go`
- [Resource Cache](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-orch/cache/resource_cache.go): `sandboxd-orch/cache/resource_cache.go`
- [Orchestrator Process](https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxorch/main.go): `cmd/sbxorch/main.go`

### Node Runtime

- [Node Agent API](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/http/handlers.go): `sandboxd-let/http/handlers.go`
- [Sandbox Service](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/sandbox/service.go): `sandboxd-let/sandbox/service.go`
- [Sandbox State](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/store/file_store.go): `sandboxd-let/store/file_store.go`
- [Sandbox Networking](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/network/firewall.go): `sandboxd-let/network/firewall.go`
- [Spec Validation](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-let/model/validate.go): `sandboxd-let/model/validate.go`

### User Interfaces

- [Sandbox CLI](https://github.com/swualabs/sandboxd-o/blob/main/cmd/sbxctl/main.go): `cmd/sbxctl/main.go`
- [Resource Commands](https://github.com/swualabs/sandboxd-o/blob/main/sandboxd-ctl/cmd/resource_cmds.go): `sandboxd-ctl/cmd/resource_cmds.go`

### Other components

- **Operator**
- **Containerd CRI**
- **Worker Node**

## Connections

- Operator → Admin CLI: runs
- Admin CLI → Cluster Operations: invokes
- Cluster Operations → AWS Resources: provisions
- Cluster Operations → Cluster Store: persists cluster
- Worker Operations → AWS Resources: provisions worker (evidence: `sandboxd-adm/orchestrate/worker.go`)
- Worker Operations → Cluster Store: persists worker (evidence: `sandboxd-adm/orchestrate/worker.go`)
- Worker Operations → Orchestrator API: registers node (evidence: `sandboxd-adm/orchestrate/worker.go`)
- Worker Operations → Worker Node: installs agent
- Operator → Sandbox CLI: runs
- Sandbox CLI → Resource Commands: dispatches
- Resource Commands → Orchestrator API: requests API
- Orchestrator Process → Orchestration Service: starts loops (evidence: `cmd/sbxorch/main.go`)
- Orchestrator Process → Orchestrator API: serves routes (evidence: `cmd/sbxorch/main.go`)
- Orchestrator API → Orchestration Service: calls (evidence: `sandboxd-orch/http/handlers/handler.go`)
- Orchestration Service → SQLite Repositories: reads and writes
- Orchestration Service → Resource Cache: uses resources
- Orchestration Service → Node Agent API: proxies node requests
- Orchestration Service → Worker Node: schedules sandboxes
- Node Agent API → Sandbox Service: calls
- Sandbox Service → Containerd CRI: creates containers (evidence: `sandboxd-let/sandbox/service.go`)
- Sandbox Service → Sandbox State: saves state (evidence: `sandboxd-let/sandbox/service.go`)
- Sandbox Service → Sandbox Networking: applies policy (evidence: `sandboxd-let/sandbox/service.go`)
- Sandbox Service → Spec Validation: validates IDs (evidence: `sandboxd-let/sandbox/service.go`)