# omdsh-dev/dsh-better-sidebar architecture

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

- Interactive diagram: https://gitdiagram.com/omdsh-dev/dsh-better-sidebar
- Repository: https://github.com/omdsh-dev/dsh-better-sidebar

## Overview

dsh-better-sidebar is a DSH plugin that provides a native right-sidebar tab system and a complementary bottom workbench, with file browsing/editing, change review, task visibility, side chat, and an extension service. The main user path is opening a session’s sidebar, selecting a file or feature tab, and using the client UI against session-scoped host APIs. The README documents major capabilities; source excerpts and the SOURCE INDEX support selected client, routing, and model links. Several UI and server subsystems are represented at subsystem level because their implementation excerpts were not supplied.

Main entry points: [`src/index.ts`](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/index.ts) (Sidebar API), [`src/client/index.tsx`](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/index.tsx) (Client bootstrap), [`src/client/api.ts`](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/api.ts) (Typed API client), [`src/client/service.ts`](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/service.ts) (Plugin registration service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Sidebar client"]
  node_client_entry["Client bootstrap<br/>[index.tsx]"]
  node_native_tabs["Native sidebar tabs<br/>[tab-adapter.tsx]"]
  node_bottom_workbench["Bottom workbench"]
  node_api_client["Typed API client<br/>[api.ts]"]
  node_session_state[("Session state<br/>[state.ts]")]
end

subgraph group_files["Files and changes"]
  node_file_tree["File explorer<br/>[FileTree.tsx]"]
  node_editor_preview["Editor and preview<br/>[EditorHost.tsx]"]
  node_change_review["Change review<br/>[ChangesTab.tsx]"]
  node_diff_render["Diff rendering<br/>[DiffPane.tsx]"]
end

subgraph group_work["Work and collaboration"]
  node_task_views["Task views<br/>[TasksGraph.tsx]"]
  node_task_model["Task model<br/>[tasks-model.ts]"]
  node_sidechat_view["Side chat<br/>[SideChatView.tsx]"]
  node_team_board["Team board<br/>[TeamBoard.tsx]"]
  node_jobs_ui["Background jobs<br/>[JobsDrawer.tsx]"]
end

subgraph group_server["Host services"]
  node_host_api["Sidebar API<br/>[index.ts]"]
  node_filesystem["Filesystem services<br/>[fs-operations.ts]"]
  node_git_service["Git services<br/>[git.ts]"]
  node_sidechat_routes["Side-chat routes<br/>[sidechat-routes.ts]"]
  node_sidechat_core["Side-chat runtime<br/>[sidechat-core.ts]"]
  node_workflow_routes["Workflow routes<br/>[workflow-routes.ts]"]
  node_team_routes["Team mutations<br/>[team-routes.ts]"]
end

subgraph group_extension["Plugin extension"]
  node_plugin_service["Plugin registration service<br/>[service.ts]"]
  node_native_surface["Native surface integration<br/>[surface.ts]"]
end

node_user(("DSH user"))
node_host{{"DSH host"}}
node_external_plugins(("Other plugins"))

node_user -->|"opens sidebar"| node_client_entry
node_host -->|"loads plugin"| node_client_entry
node_client_entry -->|"installs adapter"| node_native_tabs
node_client_entry -->|"mounts workbench"| node_bottom_workbench
node_client_entry -->|"publishes service"| node_plugin_service
node_native_tabs -->|"reads session state"| node_session_state
node_bottom_workbench -->|"persists layout"| node_session_state
node_user -->|"browses files"| node_file_tree
node_file_tree -.->|"requests file data"| node_api_client
node_user -->|"opens file"| node_editor_preview
node_editor_preview -.->|"reads and saves"| node_api_client
node_user -->|"reviews changes"| node_change_review
node_change_review -->|"renders diffs"| node_diff_render
node_user -->|"views activity"| node_task_views
node_task_views -->|"renders model"| node_task_model
node_task_model -.->|"uses workflow data"| node_host_api
node_user -->|"starts side thread"| node_sidechat_view
node_sidechat_view -.->|"sends chat actions"| node_api_client
node_user -->|"manages team tasks"| node_team_board
node_team_board -.->|"submits mutations"| node_api_client
node_user -->|"monitors jobs"| node_jobs_ui
node_api_client -->|"posts API requests"| node_host_api
node_host_api -->|"calls filesystem"| node_filesystem
node_host_api -->|"calls Git"| node_git_service
node_host_api -.->|"dispatches chat routes"| node_sidechat_routes
node_sidechat_routes -->|"resolves thread data"| node_sidechat_core
node_host_api -.->|"dispatches workflow route"| node_workflow_routes
node_host_api -.->|"dispatches team routes"| node_team_routes
node_workflow_routes -->|"reads session activity"| node_host
node_team_routes -->|"mutates team tasks"| node_host
node_external_plugins -->|"registers tabs"| node_plugin_service
node_plugin_service -->|"opens native tabs"| node_native_surface

click node_client_entry "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/index.tsx"
click node_native_tabs "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/native/tab-adapter.tsx"
click node_bottom_workbench "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/SideCardSection.tsx"
click node_file_tree "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/FileTree.tsx"
click node_editor_preview "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/EditorHost.tsx"
click node_change_review "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/changes/ChangesTab.tsx"
click node_diff_render "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/changes/DiffPane.tsx"
click node_task_views "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/TasksGraph.tsx"
click node_task_model "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/tasks-model.ts"
click node_sidechat_view "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/SideChatView.tsx"
click node_team_board "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/TeamBoard.tsx"
click node_jobs_ui "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/JobsDrawer.tsx"
click node_api_client "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/api.ts"
click node_host_api "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/index.ts"
click node_filesystem "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/fs-operations.ts"
click node_git_service "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/git.ts"
click node_sidechat_routes "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/sidechat-routes.ts"
click node_sidechat_core "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/sidechat-core.ts"
click node_workflow_routes "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/workflow-routes.ts"
click node_team_routes "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/team-routes.ts"
click node_plugin_service "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/service.ts"
click node_native_surface "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/native/surface.ts"
click node_session_state "https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/state.ts"

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_client_entry,node_native_tabs,node_bottom_workbench,node_api_client,node_session_state,node_user toneBlue
class node_file_tree,node_editor_preview,node_change_review,node_diff_render toneAmber
class node_task_views,node_task_model,node_sidechat_view,node_team_board,node_jobs_ui toneMint
class node_host_api,node_filesystem,node_git_service,node_sidechat_routes,node_sidechat_core,node_workflow_routes,node_team_routes toneRose
class node_plugin_service,node_native_surface,node_host,node_external_plugins toneIndigo
```

## Components

### Sidebar client

- [Client bootstrap](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/index.tsx): `src/client/index.tsx`
- [Native sidebar tabs](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/native/tab-adapter.tsx): `src/client/native/tab-adapter.tsx`
- [Bottom workbench](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/SideCardSection.tsx): `src/client/SideCardSection.tsx`
- [Typed API client](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/api.ts): `src/client/api.ts`
- [Session state](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/state.ts): `src/client/state.ts`

### Files and changes

- [File explorer](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/FileTree.tsx): `src/client/FileTree.tsx`
- [Editor and preview](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/EditorHost.tsx): `src/client/EditorHost.tsx`
- [Change review](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/changes/ChangesTab.tsx): `src/client/changes/ChangesTab.tsx`
- [Diff rendering](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/changes/DiffPane.tsx): `src/client/changes/DiffPane.tsx`

### Work and collaboration

- [Task views](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/TasksGraph.tsx): `src/client/TasksGraph.tsx`
- [Task model](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/tasks-model.ts): `src/client/tasks-model.ts`
- [Side chat](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/SideChatView.tsx): `src/client/SideChatView.tsx`
- [Team board](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/TeamBoard.tsx): `src/client/TeamBoard.tsx`
- [Background jobs](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/JobsDrawer.tsx): `src/client/JobsDrawer.tsx`

### Host services

- [Sidebar API](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/index.ts): `src/index.ts`
- [Filesystem services](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/fs-operations.ts): `src/fs-operations.ts`
- [Git services](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/git.ts): `src/git.ts`
- [Side-chat routes](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/sidechat-routes.ts): `src/sidechat-routes.ts`
- [Side-chat runtime](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/sidechat-core.ts): `src/sidechat-core.ts`
- [Workflow routes](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/workflow-routes.ts): `src/workflow-routes.ts`
- [Team mutations](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/team-routes.ts): `src/team-routes.ts`

### Plugin extension

- [Plugin registration service](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/service.ts): `src/client/service.ts`
- [Native surface integration](https://github.com/omdsh-dev/dsh-better-sidebar/blob/main/src/client/native/surface.ts): `src/client/native/surface.ts`

### Other components

- **DSH user**
- **DSH host**
- **Other plugins**

## Connections

- DSH user → Client bootstrap: opens sidebar (evidence: `README.md`)
- DSH host → Client bootstrap: loads plugin (evidence: `README.md`)
- Client bootstrap → Native sidebar tabs: installs adapter (evidence: `src/client/index.tsx`)
- Client bootstrap → Bottom workbench: mounts workbench (evidence: `src/client/index.tsx`)
- Client bootstrap → Plugin registration service: publishes service (evidence: `src/client/index.tsx`)
- Native sidebar tabs → Session state: reads session state (evidence: `src/client/native/tab-adapter.tsx`)
- Bottom workbench → Session state: persists layout (evidence: `README.md`)
- DSH user → File explorer: browses files (evidence: `README.md`)
- File explorer → Typed API client: requests file data
- DSH user → Editor and preview: opens file (evidence: `README.md`)
- Editor and preview → Typed API client: reads and saves
- DSH user → Change review: reviews changes (evidence: `README.md`)
- Change review → Diff rendering: renders diffs
- DSH user → Task views: views activity (evidence: `README.md`)
- Task views → Task model: renders model (evidence: `src/client/TasksGraph.tsx`)
- Task model → Sidebar API: uses workflow data
- DSH user → Side chat: starts side thread (evidence: `README.md`)
- Side chat → Typed API client: sends chat actions
- DSH user → Team board: manages team tasks (evidence: `README.md`)
- Team board → Typed API client: submits mutations
- DSH user → Background jobs: monitors jobs (evidence: `README.md`)
- Typed API client → Sidebar API: posts API requests (evidence: `src/client/api.ts`)
- Sidebar API → Filesystem services: calls filesystem (evidence: `src/index.ts`)
- Sidebar API → Git services: calls Git (evidence: `src/index.ts`)
- Sidebar API → Side-chat routes: dispatches chat routes (evidence: `src/index.ts`)
- Side-chat routes → Side-chat runtime: resolves thread data (evidence: `src/sidechat-routes.ts`)
- Sidebar API → Workflow routes: dispatches workflow route (evidence: `src/index.ts`)
- Sidebar API → Team mutations: dispatches team routes (evidence: `src/index.ts`)
- Workflow routes → DSH host: reads session activity (evidence: `src/workflow-routes.ts`)
- Team mutations → DSH host: mutates team tasks (evidence: `src/team-routes.ts`)
- Other plugins → Plugin registration service: registers tabs (evidence: `src/client/service.ts`)
- Plugin registration service → Native surface integration: opens native tabs (evidence: `src/client/service.ts`)