# watanabe3tipapa/openshell-plus architecture

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

- Interactive diagram: https://gitdiagram.com/watanabe3tipapa/openshell-plus
- Repository: https://github.com/watanabe3tipapa/openshell-plus

## Overview

openshell-plus is a browser dashboard for managing NVIDIA OpenShell sandboxes and running commands in them. A user creates or selects a sandbox, inspects its status and service URLs, then streams command output through a WebSocket console (with SSE and aggregated REST execution also available). FastAPI routes delegate sandbox and execution operations to a shared backend contract, implemented by either the OpenShell SDK adapter or an in-memory demo. Startup configuration and mode selection govern backend choice and security. The README documents several deployment modes; their deployment machinery is not mapped here. UI implementation details were not sampled, so UI-to-API links rely on README statements.

Main entry points: [`src/openshell_ui/main.py`](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/main.py) (App Lifecycle), [`src/openshell_ui/core/backends/base.py`](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/base.py) (Backend Contract), [`src/openshell_ui/core/factory.py`](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/factory.py) (Backend Selection), [`src/openshell_ui/api/sandboxes.py`](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/sandboxes.py) (Sandbox API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Browser UI"]
  node_dashboard["Dashboard<br/>[app.js]"]
end

subgraph group_service["FastAPI Service"]
  node_app["App Lifecycle<br/>[main.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
  node_mode["Run Mode<br/>[mode.py]"]
  node_auth["Request Auth<br/>[auth.py]"]
  node_sandbox_api["Sandbox API<br/>[sandboxes.py]"]
  node_exec_api["Exec API<br/>[exec.py]"]
  node_meta_api["Health and Config<br/>[meta.py]"]
end

subgraph group_backend["Backend Layer"]
  node_contract["Backend Contract<br/>[base.py]"]
  node_factory["Backend Selection<br/>[factory.py]"]
  node_openshell_backend["OpenShell Adapter"]
  node_demo_backend["Demo Backend<br/>[demo.py]"]
end

subgraph group_runtime["Sandbox Runtime"]
  node_gateway{{"OpenShell Gateway"}}
  node_sandbox["Sandbox"]
end

node_user(("Dashboard User"))

node_user -->|"operates"| node_dashboard
node_dashboard -->|"manages sandboxes"| node_sandbox_api
node_dashboard -->|"streams commands"| node_exec_api
node_app -->|"loads settings"| node_settings
node_app -->|"detects mode"| node_mode
node_app -->|"creates backend"| node_factory
node_app -->|"registers router"| node_sandbox_api
node_app -->|"registers router"| node_exec_api
node_app -->|"registers router"| node_meta_api
node_sandbox_api -->|"requires auth"| node_auth
node_exec_api -->|"requires auth"| node_auth
node_sandbox_api -->|"calls backend"| node_contract
node_exec_api -->|"streams execution"| node_contract
node_meta_api -->|"checks health"| node_contract
node_factory -->|"probes gateway"| node_openshell_backend
node_factory -->|"falls back"| node_demo_backend
node_factory -->|"returns backend"| node_contract
node_openshell_backend -->|"calls SDK"| node_gateway
node_demo_backend -->|"implements"| node_contract
node_openshell_backend -->|"implements"| node_contract
node_gateway -->|"manages"| node_sandbox

click node_dashboard "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/ui/assets/app.js"
click node_app "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/main.py"
click node_settings "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/config.py"
click node_mode "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/mode.py"
click node_auth "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/auth.py"
click node_sandbox_api "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/sandboxes.py"
click node_exec_api "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/exec.py"
click node_meta_api "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/meta.py"
click node_contract "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/base.py"
click node_factory "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/factory.py"
click node_openshell_backend "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/openshell_backend.py"
click node_demo_backend "https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/demo.py"

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_dashboard,node_user toneBlue
class node_app,node_settings,node_mode,node_auth,node_sandbox_api,node_exec_api,node_meta_api toneAmber
class node_contract,node_factory,node_openshell_backend,node_demo_backend toneMint
class node_gateway,node_sandbox toneRose
```

## Components

### Browser UI

- [Dashboard](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/ui/assets/app.js): `src/openshell_ui/ui/assets/app.js`

### FastAPI Service

- [App Lifecycle](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/main.py): `src/openshell_ui/main.py`
- [Runtime Settings](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/config.py): `src/openshell_ui/core/config.py`
- [Run Mode](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/mode.py): `src/openshell_ui/core/mode.py`
- [Request Auth](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/auth.py): `src/openshell_ui/api/auth.py`
- [Sandbox API](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/sandboxes.py): `src/openshell_ui/api/sandboxes.py`
- [Exec API](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/exec.py): `src/openshell_ui/api/exec.py`
- [Health and Config](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/api/meta.py): `src/openshell_ui/api/meta.py`

### Backend Layer

- [Backend Contract](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/base.py): `src/openshell_ui/core/backends/base.py`
- [Backend Selection](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/factory.py): `src/openshell_ui/core/factory.py`
- [OpenShell Adapter](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/openshell_backend.py): `src/openshell_ui/core/backends/openshell_backend.py`
- [Demo Backend](https://github.com/watanabe3tipapa/openshell-plus/blob/main/src/openshell_ui/core/backends/demo.py): `src/openshell_ui/core/backends/demo.py`

### Sandbox Runtime

- **OpenShell Gateway**
- **Sandbox**

### Other components

- **Dashboard User**

## Connections

- Dashboard User → Dashboard: operates (evidence: `README.md`)
- Dashboard → Sandbox API: manages sandboxes (evidence: `README.md`)
- Dashboard → Exec API: streams commands (evidence: `README.md`)
- App Lifecycle → Runtime Settings: loads settings (evidence: `src/openshell_ui/main.py`)
- App Lifecycle → Run Mode: detects mode (evidence: `src/openshell_ui/main.py`)
- App Lifecycle → Backend Selection: creates backend (evidence: `src/openshell_ui/main.py`)
- App Lifecycle → Sandbox API: registers router (evidence: `src/openshell_ui/main.py`)
- App Lifecycle → Exec API: registers router (evidence: `src/openshell_ui/main.py`)
- App Lifecycle → Health and Config: registers router (evidence: `src/openshell_ui/main.py`)
- Sandbox API → Request Auth: requires auth (evidence: `src/openshell_ui/api/sandboxes.py`)
- Exec API → Request Auth: requires auth (evidence: `src/openshell_ui/api/exec.py`)
- Sandbox API → Backend Contract: calls backend (evidence: `src/openshell_ui/api/sandboxes.py`)
- Exec API → Backend Contract: streams execution (evidence: `src/openshell_ui/api/exec.py`)
- Health and Config → Backend Contract: checks health (evidence: `src/openshell_ui/api/meta.py`)
- Backend Selection → OpenShell Adapter: probes gateway (evidence: `src/openshell_ui/core/factory.py`)
- Backend Selection → Demo Backend: falls back (evidence: `src/openshell_ui/core/factory.py`)
- Backend Selection → Backend Contract: returns backend (evidence: `src/openshell_ui/core/factory.py`)
- OpenShell Adapter → OpenShell Gateway: calls SDK (evidence: `README.md`)
- Demo Backend → Backend Contract: implements (evidence: `src/openshell_ui/core/backends/demo.py`)
- OpenShell Adapter → Backend Contract: implements (evidence: `src/openshell_ui/core/backends/openshell_backend.py`)
- OpenShell Gateway → Sandbox: manages (evidence: `README.md`)
