# blank-not-black/dsh-remote architecture

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

- Interactive diagram: https://gitdiagram.com/blank-not-black/dsh-remote
- Repository: https://github.com/blank-not-black/dsh-remote

## Overview

DSH Remote lets a user pair a phone, browser, or desktop client with a DSH host, then continue session work remotely: inspect conversations, respond to approvals and questions, manage files, and inspect host state. The plugin provides the DSH entry point and manages a gateway; the gateway authenticates and proxies HTTP/realtime traffic. An optional relay supports remote connectivity, while Android adds native transport, polling, downloads, and notifications. The README documents capabilities whose implementation was not sampled; those are represented at their existing client or plugin paths without asserting unsourced call chains.

Main entry points: [`android/app/src/main/java/com/dshremote/app/MainActivity.java`](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/MainActivity.java) (Android shell), [`packages/plugin/index.mjs`](https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/index.mjs) (Plugin entry), [`public/app.js`](https://github.com/blank-not-black/dsh-remote/blob/main/public/app.js) (Web and desktop UI), [`gateway.js`](https://github.com/blank-not-black/dsh-remote/blob/main/gateway.js) (Gateway runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["DSH Plugin"]
  node_plugin_entry["Plugin entry<br/>[index.mjs]"]
  node_doctor["Doctor guidance<br/>[doctor-skill.mjs]"]
  node_plugin_center["Plugin center<br/>[plugin-center.mjs]"]
  node_plugin_features["Session features"]
end

subgraph group_gateway["Gateway and Sessions"]
  node_gateway_runtime["Gateway runtime<br/>[gateway.js]"]
  node_stats["Gateway stats<br/>[gateway-stats.cjs]"]
end

subgraph group_relay["Optional Relay"]
  node_relay_client["Relay client<br/>[client.cjs]"]
  node_relay_broker["Relay broker<br/>[broker.cjs]"]
  node_relay_registry[("Grant registry<br/>[registry.cjs]")]
  node_relay_portal["Sponsor portal<br/>[portal.js]"]
end

subgraph group_clients["Remote Clients"]
  node_web_client["Web and desktop UI<br/>[app.js]"]
  node_session_ui["Session views<br/>[session-deck.js]"]
  node_file_ui["File previews<br/>[image-preview.js]"]
  node_workflow_ui["Guides and workflow<br/>[workflow.js]"]
  node_android_shell["Android shell<br/>[MainActivity.java]"]
  node_android_poll["Background polling"]
  node_android_notify["Attention notifications"]
  node_android_reminders["Usage reminders"]
  node_android_e2ee["Encrypted transport<br/>[E2eeBridge.java]"]
  node_android_downloads["Encrypted downloads"]
  node_lan_pairing["LAN discovery<br/>[LanDiscovery.java]"]
end

subgraph group_feedback["Feedback Service"]
  node_feedback_server["Feedback collector<br/>[server.py]"]
  node_poll_tallies["Public poll tallies<br/>[public_polls.py]"]
end

node_user(("Remote user"))
node_dsh(("DSH host"))

node_user -->|"uses"| node_web_client
node_user -->|"uses"| node_android_shell
node_web_client -->|"connects to"| node_gateway_runtime
node_android_shell -->|"connects to"| node_gateway_runtime
node_dsh -->|"hosts"| node_plugin_entry
node_plugin_entry -->|"manages"| node_gateway_runtime
node_plugin_entry -->|"includes"| node_doctor
node_plugin_entry -->|"includes"| node_plugin_center
node_plugin_entry -->|"provides"| node_plugin_features
node_gateway_runtime -->|"uses"| node_stats
node_web_client -->|"renders"| node_session_ui
node_web_client -->|"renders"| node_file_ui
node_web_client -->|"includes"| node_workflow_ui
node_android_shell -->|"starts"| node_android_poll
node_android_shell -->|"uses"| node_android_notify
node_android_shell -->|"uses"| node_android_reminders
node_android_shell -->|"exposes"| node_android_e2ee
node_android_shell -->|"routes downloads"| node_android_downloads
node_android_shell -->|"exposes"| node_lan_pairing
node_relay_client -.->|"tunnels to"| node_relay_broker
node_relay_broker -->|"checks grants"| node_relay_registry
node_relay_broker -->|"proxies traffic"| node_gateway_runtime
node_relay_portal -.->|"manages access"| node_relay_registry
node_feedback_server -->|"uses tallies"| node_poll_tallies
node_user -.->|"sends feedback"| node_feedback_server

click node_plugin_entry "https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/index.mjs"
click node_doctor "https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/doctor-skill.mjs"
click node_plugin_center "https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/plugin-center.mjs"
click node_plugin_features "https://github.com/blank-not-black/dsh-remote/tree/main/packages/plugin"
click node_gateway_runtime "https://github.com/blank-not-black/dsh-remote/blob/main/gateway.js"
click node_stats "https://github.com/blank-not-black/dsh-remote/blob/main/gateway-stats.cjs"
click node_web_client "https://github.com/blank-not-black/dsh-remote/blob/main/public/app.js"
click node_session_ui "https://github.com/blank-not-black/dsh-remote/blob/main/public/session-deck.js"
click node_file_ui "https://github.com/blank-not-black/dsh-remote/blob/main/public/image-preview.js"
click node_workflow_ui "https://github.com/blank-not-black/dsh-remote/blob/main/public/workflow.js"
click node_android_shell "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/MainActivity.java"
click node_android_poll "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/RemotePollService.java"
click node_android_notify "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/PendingNotifications.java"
click node_android_reminders "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/PeakReminderService.java"
click node_android_e2ee "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/E2eeBridge.java"
click node_android_downloads "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/EncryptedDownloads.java"
click node_lan_pairing "https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/LanDiscovery.java"
click node_relay_client "https://github.com/blank-not-black/dsh-remote/blob/main/relay/client.cjs"
click node_relay_broker "https://github.com/blank-not-black/dsh-remote/blob/main/relay/broker.cjs"
click node_relay_registry "https://github.com/blank-not-black/dsh-remote/blob/main/relay/registry.cjs"
click node_relay_portal "https://github.com/blank-not-black/dsh-remote/blob/main/relay/sponsor/portal.js"
click node_feedback_server "https://github.com/blank-not-black/dsh-remote/blob/main/ops/feedback-collector/server.py"
click node_poll_tallies "https://github.com/blank-not-black/dsh-remote/blob/main/ops/feedback-collector/public_polls.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_plugin_entry,node_doctor,node_plugin_center,node_plugin_features,node_user toneBlue
class node_gateway_runtime,node_stats toneAmber
class node_relay_client,node_relay_broker,node_relay_registry,node_relay_portal toneMint
class node_web_client,node_session_ui,node_file_ui,node_workflow_ui,node_android_shell,node_android_poll,node_android_notify,node_android_reminders,node_android_e2ee,node_android_downloads,node_lan_pairing toneRose
class node_feedback_server,node_poll_tallies,node_dsh toneIndigo
```

## Components

### DSH Plugin

- [Plugin entry](https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/index.mjs): `packages/plugin/index.mjs`
- [Doctor guidance](https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/doctor-skill.mjs): `packages/plugin/doctor-skill.mjs`
- [Plugin center](https://github.com/blank-not-black/dsh-remote/blob/main/packages/plugin/plugin-center.mjs): `packages/plugin/plugin-center.mjs`
- [Session features](https://github.com/blank-not-black/dsh-remote/tree/main/packages/plugin): `packages/plugin`

### Gateway and Sessions

- [Gateway runtime](https://github.com/blank-not-black/dsh-remote/blob/main/gateway.js): `gateway.js`
- [Gateway stats](https://github.com/blank-not-black/dsh-remote/blob/main/gateway-stats.cjs): `gateway-stats.cjs`

### Optional Relay

- [Relay client](https://github.com/blank-not-black/dsh-remote/blob/main/relay/client.cjs): `relay/client.cjs`
- [Relay broker](https://github.com/blank-not-black/dsh-remote/blob/main/relay/broker.cjs): `relay/broker.cjs`
- [Grant registry](https://github.com/blank-not-black/dsh-remote/blob/main/relay/registry.cjs): `relay/registry.cjs`
- [Sponsor portal](https://github.com/blank-not-black/dsh-remote/blob/main/relay/sponsor/portal.js): `relay/sponsor/portal.js`

### Remote Clients

- [Web and desktop UI](https://github.com/blank-not-black/dsh-remote/blob/main/public/app.js): `public/app.js`
- [Session views](https://github.com/blank-not-black/dsh-remote/blob/main/public/session-deck.js): `public/session-deck.js`
- [File previews](https://github.com/blank-not-black/dsh-remote/blob/main/public/image-preview.js): `public/image-preview.js`
- [Guides and workflow](https://github.com/blank-not-black/dsh-remote/blob/main/public/workflow.js): `public/workflow.js`
- [Android shell](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/MainActivity.java): `android/app/src/main/java/com/dshremote/app/MainActivity.java`
- [Background polling](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/RemotePollService.java): `android/app/src/main/java/com/dshremote/app/RemotePollService.java`
- [Attention notifications](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/PendingNotifications.java): `android/app/src/main/java/com/dshremote/app/PendingNotifications.java`
- [Usage reminders](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/PeakReminderService.java): `android/app/src/main/java/com/dshremote/app/PeakReminderService.java`
- [Encrypted transport](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/E2eeBridge.java): `android/app/src/main/java/com/dshremote/app/E2eeBridge.java`
- [Encrypted downloads](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/EncryptedDownloads.java): `android/app/src/main/java/com/dshremote/app/EncryptedDownloads.java`
- [LAN discovery](https://github.com/blank-not-black/dsh-remote/blob/main/android/app/src/main/java/com/dshremote/app/LanDiscovery.java): `android/app/src/main/java/com/dshremote/app/LanDiscovery.java`

### Feedback Service

- [Feedback collector](https://github.com/blank-not-black/dsh-remote/blob/main/ops/feedback-collector/server.py): `ops/feedback-collector/server.py`
- [Public poll tallies](https://github.com/blank-not-black/dsh-remote/blob/main/ops/feedback-collector/public_polls.py): `ops/feedback-collector/public_polls.py`

### Other components

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

## Connections

- Remote user → Web and desktop UI: uses (evidence: `README.md`)
- Remote user → Android shell: uses (evidence: `README.md`)
- Web and desktop UI → Gateway runtime: connects to (evidence: `README.md`)
- Android shell → Gateway runtime: connects to (evidence: `README.md`)
- DSH host → Plugin entry: hosts (evidence: `README.md`)
- Plugin entry → Gateway runtime: manages (evidence: `README.md`)
- Plugin entry → Doctor guidance: includes (evidence: `packages/plugin/index.mjs`)
- Plugin entry → Plugin center: includes (evidence: `packages/plugin/index.mjs`)
- Plugin entry → Session features: provides (evidence: `packages/plugin/index.mjs`)
- Gateway runtime → Gateway stats: uses (evidence: `gateway.js`)
- Web and desktop UI → Session views: renders (evidence: `README.md`)
- Web and desktop UI → File previews: renders (evidence: `README.md`)
- Web and desktop UI → Guides and workflow: includes (evidence: `README.md`)
- Android shell → Background polling: starts (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Android shell → Attention notifications: uses (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Android shell → Usage reminders: uses (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Android shell → Encrypted transport: exposes (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Android shell → Encrypted downloads: routes downloads (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Android shell → LAN discovery: exposes (evidence: `android/app/src/main/java/com/dshremote/app/MainActivity.java`)
- Relay client → Relay broker: tunnels to
- Relay broker → Grant registry: checks grants (evidence: `relay/broker.cjs`)
- Relay broker → Gateway runtime: proxies traffic (evidence: `relay/broker.cjs`)
- Sponsor portal → Grant registry: manages access
- Feedback collector → Public poll tallies: uses tallies (evidence: `ops/feedback-collector/server.py`)
- Remote user → Feedback collector: sends feedback