# dobychao/dsh-workspace-enhancement architecture

> Architecture diagram of the GitHub repository dobychao/dsh-workspace-enhancement, 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/dobychao/dsh-workspace-enhancement
- Repository: https://github.com/dobychao/dsh-workspace-enhancement

## Overview

This is a DeepSeek Harness plugin for managing local and SSH workspaces together. The principal workflow starts with a user adding or selecting a machine and directory, then attaching that workspace to a session; the plugin routes subprocess and filesystem operations to the appropriate local or remote environment and returns results to the Harness. Other major capabilities include machine and host-key management, session context and side workspaces, connection status, remote file browsing, command approval, and a remote sandbox fence. Some implementation paths are unsampled, so those relationships are shown only where documented or evidenced by imports.

Main entry points: [`src/web-channel.ts`](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/web-channel.ts) (Web channel), [`src/registry.ts`](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/registry.ts) (Machine registry), [`src/client/flow.tsx`](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/flow.tsx) (Workspace picker), [`src/client/settings.tsx`](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/settings.tsx) (Machine settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_flow["Workspace picker<br/>[flow.tsx]"]
  node_machineform["Machine form<br/>[machine-form.tsx]"]
  node_settings["Machine settings<br/>[settings.tsx]"]
  node_filebrowse["Remote file browser<br/>[remote-files.ts]"]
  node_statusui["Connection status UI<br/>[status.tsx]"]
  node_rowbadges["Sidebar status badges<br/>[row-badges.ts]"]
  node_icons["Client icons<br/>[icons.tsx]"]
  node_uihelpers["Client UI helpers<br/>[ui.ts]"]
end

subgraph group_sessions["Session workspaces"]
  node_sessionroots[("Session workspace roots")]
  node_sessioncontext["Session remote context"]
end

subgraph group_remote["Remote access"]
  node_channel["Web channel<br/>[web-channel.ts]"]
  node_web["Web endpoints<br/>[web.ts]"]
  node_registry[("Machine registry<br/>[registry.ts]")]
  node_hostkeys[("Host-key trust<br/>[hostkey.ts]")]
  node_connection["SSH connection<br/>[connection.ts]"]
  node_transport["Route resolution<br/>[transport.ts]"]
  node_sshcore["SSH operations<br/>[ssh-core.ts]"]
  node_subprocess["Remote subprocess<br/>[subprocess.ts]"]
  node_filesystem["Remote filesystem<br/>[filesystem.ts]"]
end

subgraph group_safety["Execution safety"]
  node_approval["Command approval gate"]
  node_sandbox["Sandbox policy<br/>[remote-sandbox.ts]"]
  node_fence["Core sandbox fence<br/>[fence_tier.go]"]
end

node_user(("Harness user"))
node_harness(("DSH Harness"))
node_remotehost(("Remote host"))

node_user -->|"selects workspace"| node_flow
node_flow -->|"creates connection"| node_machineform
node_flow -->|"uses channel"| node_channel
node_user -->|"manages machines"| node_settings
node_settings -->|"uses form"| node_machineform
node_settings -->|"requests status"| node_channel
node_filebrowse -->|"uses channel"| node_channel
node_rowbadges -->|"uses fallback"| node_statusui
node_rowbadges -->|"probes connections"| node_channel
node_harness -->|"mounts plugin"| node_channel
node_channel -.->|"routes requests"| node_web
node_web -.->|"manages connections"| node_registry
node_registry -->|"checks trust"| node_hostkeys
node_registry -->|"resolves connections"| node_connection
node_transport -->|"resolves route"| node_registry
node_harness -->|"runs commands"| node_subprocess
node_harness -->|"uses filesystem"| node_filesystem
node_subprocess -.->|"routes execution"| node_transport
node_filesystem -.->|"routes file access"| node_transport
node_connection -->|"connects by SSH"| node_remotehost
node_subprocess -->|"runs commands"| node_remotehost
node_filesystem -->|"accesses files"| node_remotehost
node_user -->|"attaches directories"| node_sessionroots
node_sessionroots -->|"provides workspace context"| node_sessioncontext
node_harness -->|"receives session context"| node_sessioncontext
node_registry -->|"configures optional gate"| node_approval
node_approval -->|"gates commands"| node_remotehost
node_sandbox -.->|"applies execution fence"| node_fence
node_fence -.->|"confines execution"| node_remotehost

click node_flow "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/flow.tsx"
click node_machineform "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/machine-form.tsx"
click node_settings "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/settings.tsx"
click node_filebrowse "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/remote-files.ts"
click node_statusui "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/status.tsx"
click node_rowbadges "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/row-badges.ts"
click node_icons "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/icons.tsx"
click node_uihelpers "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/ui.ts"
click node_channel "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/web-channel.ts"
click node_web "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/web.ts"
click node_registry "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/registry.ts"
click node_hostkeys "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/hostkey.ts"
click node_connection "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/connection.ts"
click node_transport "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/transport.ts"
click node_sshcore "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/ssh-core.ts"
click node_subprocess "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/subprocess.ts"
click node_filesystem "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/filesystem.ts"
click node_sessionroots "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/session-workspaces.ts"
click node_sessioncontext "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/session-remote-context.ts"
click node_approval "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/remote-approval-gate.ts"
click node_sandbox "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/remote-sandbox.ts"
click node_fence "https://github.com/dobychao/dsh-workspace-enhancement/blob/master/core/fence_tier.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_flow,node_machineform,node_settings,node_filebrowse,node_statusui,node_rowbadges,node_icons,node_uihelpers,node_user toneBlue
class node_sessionroots,node_sessioncontext toneAmber
class node_channel,node_web,node_registry,node_hostkeys,node_connection,node_transport,node_sshcore,node_subprocess,node_filesystem toneMint
class node_approval,node_sandbox,node_fence toneRose
class node_harness,node_remotehost toneIndigo
```

## Components

### Client experience

- [Workspace picker](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/flow.tsx): `src/client/flow.tsx`
- [Machine form](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/machine-form.tsx): `src/client/machine-form.tsx`
- [Machine settings](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/settings.tsx): `src/client/settings.tsx`
- [Remote file browser](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/remote-files.ts): `src/client/remote-files.ts`
- [Connection status UI](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/status.tsx): `src/client/status.tsx`
- [Sidebar status badges](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/row-badges.ts): `src/client/row-badges.ts`
- [Client icons](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/icons.tsx): `src/client/icons.tsx`
- [Client UI helpers](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/client/ui.ts): `src/client/ui.ts`

### Session workspaces

- [Session workspace roots](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/session-workspaces.ts): `src/session-workspaces.ts`
- [Session remote context](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/session-remote-context.ts): `src/session-remote-context.ts`

### Remote access

- [Web channel](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/web-channel.ts): `src/web-channel.ts`
- [Web endpoints](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/web.ts): `src/web.ts`
- [Machine registry](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/registry.ts): `src/registry.ts`
- [Host-key trust](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/hostkey.ts): `src/hostkey.ts`
- [SSH connection](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/connection.ts): `src/connection.ts`
- [Route resolution](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/transport.ts): `src/transport.ts`
- [SSH operations](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/ssh-core.ts): `src/ssh-core.ts`
- [Remote subprocess](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/subprocess.ts): `src/subprocess.ts`
- [Remote filesystem](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/filesystem.ts): `src/filesystem.ts`

### Execution safety

- [Command approval gate](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/remote-approval-gate.ts): `src/remote-approval-gate.ts`
- [Sandbox policy](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/src/remote-sandbox.ts): `src/remote-sandbox.ts`
- [Core sandbox fence](https://github.com/dobychao/dsh-workspace-enhancement/blob/master/core/fence_tier.go): `core/fence_tier.go`

### Other components

- **Harness user**
- **DSH Harness**
- **Remote host**

## Connections

- Harness user → Workspace picker: selects workspace (evidence: `README.md`)
- Workspace picker → Machine form: creates connection (evidence: `src/client/flow.tsx`)
- Workspace picker → Web channel: uses channel (evidence: `src/client/index.ts`)
- Harness user → Machine settings: manages machines (evidence: `README.md`)
- Machine settings → Machine form: uses form (evidence: `src/client/settings.tsx`)
- Machine settings → Web channel: requests status (evidence: `src/client/settings.tsx`)
- Remote file browser → Web channel: uses channel (evidence: `src/client/remote-files-panel.tsx`)
- Sidebar status badges → Connection status UI: uses fallback (evidence: `src/client/row-badges.ts`)
- Sidebar status badges → Web channel: probes connections (evidence: `src/client/index.ts`)
- DSH Harness → Web channel: mounts plugin
- Web channel → Web endpoints: routes requests
- Web endpoints → Machine registry: manages connections
- Machine registry → Host-key trust: checks trust (evidence: `src/registry.ts`)
- Machine registry → SSH connection: resolves connections (evidence: `src/registry.ts`)
- Route resolution → Machine registry: resolves route (evidence: `src/transport.ts`)
- DSH Harness → Remote subprocess: runs commands (evidence: `README.md`)
- DSH Harness → Remote filesystem: uses filesystem (evidence: `README.md`)
- Remote subprocess → Route resolution: routes execution
- Remote filesystem → Route resolution: routes file access
- SSH connection → Remote host: connects by SSH (evidence: `README.md`)
- Remote subprocess → Remote host: runs commands (evidence: `README.md`)
- Remote filesystem → Remote host: accesses files (evidence: `README.md`)
- Harness user → Session workspace roots: attaches directories (evidence: `README.md`)
- Session workspace roots → Session remote context: provides workspace context (evidence: `src/session-remote-context.ts`)
- DSH Harness → Session remote context: receives session context (evidence: `README.md`)
- Machine registry → Command approval gate: configures optional gate (evidence: `src/registry.ts`)
- Command approval gate → Remote host: gates commands (evidence: `README.md`)
- Sandbox policy → Core sandbox fence: applies execution fence
- Core sandbox fence → Remote host: confines execution
