# syv-ai/dash architecture

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

- Interactive diagram: https://gitdiagram.com/syv-ai/dash
- Repository: https://github.com/syv-ai/dash

## Overview

1. **Overall shape**
   - Dash is an Electron desktop app with a hard process split: the **main process** owns filesystem, Git, terminal/PTY, database, worktree, and external API access; the **renderer** owns all interactive UI and local view state.
   - The app is organized around **projects** and **tasks**. Each task maps to an isolated **Git worktree** and runs Claude Code in its own terminal session.

2. **Core domain model**
   - The primary entities are `project`, `task`, and related task metadata such as conversations, branches, comments, ports, and settings.
   - The shared model lives in `src/shared` and is consumed by both sides of the boundary, which keeps the renderer UI and main-process services aligned on task/project types and protocol shapes.

3. **Persistence boundary**
   - Persistent app state is stored in **SQLite** via **better-sqlite3** and **Drizzle** under `src/main/db`.
   - The DB appears to be the source of truth for projects, tasks, and conversation/history data; `DatabaseService` and `dbIpc.ts` mediate access so the renderer never touches storage directly.

4. **Main-process orchestration**
   - `main.ts`, `window.ts`, and `preload.ts` form the Electron bootstrap path: window creation, app initialization, and the `contextBridge` API exposure to the renderer.
   - `src/main/services` contains the real backend logic, with services for Git, worktrees, PTY management, file watching, auto-update, telemetry, and external integrations.

5. **IPC as the architectural seam**
   - The renderer communicates with the backend only through typed IPC modules in `src/main/ipc`.
   - These handlers are grouped by concern: app/system, database, Git, PTY, worktrees, GitHub, Azure DevOps, plugins, ports, sessions, skills, telemetry, and auto-update. This is the main boundary to draw in the architecture diagram.

6. **Renderer/UI structure**
   - The renderer is a React application rooted at `src/renderer/App.tsx`, with global keyboard handling, layout state, and top-level modal/drawer orchestration.
   - Major UI regions are the **left sidebar** for projects/tasks, the **main content** area for project overview or active task, and the **right inspector / drawers** for ports, shell, and task-related tooling.

7. **Task execution and terminal subsystem**
   - Terminal execution is built on **node-pty** in the main process and **xterm.js** in the renderer.
   - `ptyManager`, `TerminalSnapshotService`, `SessionRegistry`, and `TerminalSessionManager` indicate that task terminals are stateful, can be switched between, and persist via snapshots rather than being recreated every time.

8. **Worktree-centric execution model**
   - Each task gets its own Git worktree, branch, and shell context; worktree creation/removal/claiming is handled in the main process through worktree services and IPC.
   - `WorktreePoolService` suggests a pre-warmed reserve pool so task startup is fast, while `WorkspaceConfigService` and related hooks indicate per-project setup steps run after worktree creation.

9. **Git and file-change flows**
   - Git status, diffs, staging, commits, and commit-graph data are backend responsibilities exposed through `gitIpc.ts` and `GitService`.
   - The renderer’s file changes and diff editor components consume that data to show staged/unstaged files, unified diffs, blame, inline comments, and commit graph visualization.

10. **External integrations**
   - GitHub and Azure DevOps are first-class integrations, each with dedicated IPC/services for issue/work-item search, PR detection, and branch comment automation.
   - Secrets/configuration for ADO are handled per project, and the UI exposes setup flows for linking work items/issues to tasks.

11. **Runtime automation and background services**
   - Several backend services run continuously or reactively: file watching, activity monitoring, port allocation/liveness, session watching, remote control, telemetry, and auto-update.
   - These services provide the data that powers desktop notifications, busy/idle indicators, sound alerts, port onboarding, and update prompts.

12. **Onboarding and wizard flow**
   - The `src/main/wizard` subsystem is a separate orchestration layer for guided setup experiences, especially ports onboarding/setup.
   - Wizards are started conditionally, mediated by a wizard host/orchestrator, and surfaced in the renderer through dedicated modal/toast components.

13. **Settings and local UI state**
   - Renderer stores under `src/renderer/stores` hold UI state, settings, project lists, comments, runtime flags, and derived views.
   - Settings are likely persisted through the main DB or a storage abstraction, while renderer stores fan out into the UI for fast local updates and consistent modal/sidebar behavior.

14. **Key architecture boundary to diagram**
   - The most important diagram line is: **React renderer ⇄ typed IPC/preload ⇄ Electron main services ⇄ SQLite/Git/PTY/worktrees/external APIs**.
   - Everything user-facing in the renderer is a projection of backend state and events; the backend owns side effects, persistence, and integrations.

Main entry points: [`src/main/ipc/index.ts`](https://github.com/syv-ai/dash/blob/main/src/main/ipc/index.ts) (IPC handlers), [`src/renderer/App.tsx`](https://github.com/syv-ai/dash/blob/main/src/renderer/App.tsx) (App shell), [`src/main/services/ServiceRunner.ts`](https://github.com/syv-ai/dash/blob/main/src/main/services/ServiceRunner.ts) (Background services), [`src/renderer/components/MainContent.tsx`](https://github.com/syv-ai/dash/blob/main/src/renderer/components/MainContent.tsx) (Main content)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Main process"]
  node_main_entry["Main entry<br/>bootstrap<br/>[entry.ts]"]
  node_main_window["Window<br/>electron shell<br/>[window.ts]"]
  node_main_preload["Preload<br/>bridge<br/>[preload.ts]"]
  node_main_ipc["IPC handlers<br/>typed IPC<br/>[index.ts]"]
  node_main_db[("Database<br/>sqlite repo<br/>[client.ts]")]
  node_main_db_service["DB service<br/>persistence service<br/>[DatabaseService.ts]"]
  node_main_git["Git service<br/>vcs service<br/>[GitService.ts]"]
  node_main_worktree["Worktrees<br/>workspace service<br/>[WorktreeService.ts]"]
  node_main_pty["PTY manager<br/>terminal backend<br/>[ptyManager.ts]"]
  node_main_snapshot["Snapshots<br/>terminal state"]
  node_main_services["Background services<br/>runtime services<br/>[ServiceRunner.ts]"]
  node_main_wizard["Wizards<br/>onboarding orchestrator"]
end

subgraph group_renderer["Renderer"]
  node_renderer_app["App shell<br/>react root<br/>[App.tsx]"]
  node_renderer_left["Left sidebar<br/>navigation UI<br/>[LeftSidebar.tsx]"]
  node_renderer_main["Main content<br/>workspace UI<br/>[MainContent.tsx]"]
  node_renderer_diff["Diff editor<br/>review UI<br/>[DiffEditor.tsx]"]
  node_renderer_terminal["Terminal UI<br/>[TerminalPane.tsx]"]
  node_renderer_right["Right inspector<br/>tooling UI<br/>[RightInspector.tsx]"]
  node_renderer_stores["Stores<br/>local state<br/>[projectsStore.ts]"]
end

subgraph group_shared["Shared"]
  node_shared_models["Shared models<br/>domain types<br/>[types.ts]"]
end

node_main_entry -->|"creates"| node_main_window
node_main_window -->|"exposes"| node_main_preload
node_main_preload -->|"API to UI"| node_renderer_app
node_main_entry -->|"registers"| node_main_ipc
node_renderer_app -->|"requests"| node_main_ipc
node_main_ipc -->|"database"| node_main_db_service
node_main_db_service -->|"reads/writes"| node_main_db
node_main_ipc -->|"git"| node_main_git
node_main_ipc -->|"worktrees"| node_main_worktree
node_main_ipc -->|"pty"| node_main_pty
node_main_pty -->|"snapshots"| node_main_snapshot
node_main_ipc -->|"services"| node_main_services
node_main_ipc -->|"wizards"| node_main_wizard
node_main_services -->|"uses"| node_main_git
node_main_services -->|"watches"| node_main_pty
node_main_services -->|"coordinates"| node_main_worktree
node_renderer_app -->|"state"| node_renderer_stores
node_renderer_app -->|"lays out"| node_renderer_left
node_renderer_app -->|"lays out"| node_renderer_main
node_renderer_app -->|"lays out"| node_renderer_right
node_renderer_main -->|"opens"| node_renderer_diff
node_renderer_main -->|"opens"| node_renderer_terminal
node_renderer_right -->|"supports"| node_renderer_diff
node_renderer_stores -->|"uses"| node_shared_models
node_main_ipc -->|"types"| node_shared_models
node_main_wizard -->|"surfaces"| node_renderer_app
node_main_services -->|"tracks"| node_main_db_service

click node_main_entry "https://github.com/syv-ai/dash/blob/main/src/main/entry.ts"
click node_main_window "https://github.com/syv-ai/dash/blob/main/src/main/window.ts"
click node_main_preload "https://github.com/syv-ai/dash/blob/main/src/main/preload.ts"
click node_main_ipc "https://github.com/syv-ai/dash/blob/main/src/main/ipc/index.ts"
click node_main_db "https://github.com/syv-ai/dash/blob/main/src/main/db/client.ts"
click node_main_db_service "https://github.com/syv-ai/dash/blob/main/src/main/services/DatabaseService.ts"
click node_main_git "https://github.com/syv-ai/dash/blob/main/src/main/services/GitService.ts"
click node_main_worktree "https://github.com/syv-ai/dash/blob/main/src/main/services/WorktreeService.ts"
click node_main_pty "https://github.com/syv-ai/dash/blob/main/src/main/services/ptyManager.ts"
click node_main_snapshot "https://github.com/syv-ai/dash/blob/main/src/main/services/TerminalSnapshotService.ts"
click node_main_services "https://github.com/syv-ai/dash/blob/main/src/main/services/ServiceRunner.ts"
click node_main_wizard "https://github.com/syv-ai/dash/blob/main/src/main/wizard/WizardOrchestrator.ts"
click node_renderer_app "https://github.com/syv-ai/dash/blob/main/src/renderer/App.tsx"
click node_renderer_left "https://github.com/syv-ai/dash/blob/main/src/renderer/components/leftSidebar/LeftSidebar.tsx"
click node_renderer_main "https://github.com/syv-ai/dash/blob/main/src/renderer/components/MainContent.tsx"
click node_renderer_diff "https://github.com/syv-ai/dash/blob/main/src/renderer/components/diffEditor/DiffEditor.tsx"
click node_renderer_terminal "https://github.com/syv-ai/dash/blob/main/src/renderer/components/terminal/TerminalPane.tsx"
click node_renderer_right "https://github.com/syv-ai/dash/blob/main/src/renderer/components/rightInspector/RightInspector.tsx"
click node_renderer_stores "https://github.com/syv-ai/dash/blob/main/src/renderer/stores/projectsStore.ts"
click node_shared_models "https://github.com/syv-ai/dash/blob/main/src/shared/types.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_main_entry,node_main_window,node_main_preload,node_main_ipc,node_main_db,node_main_db_service,node_main_git,node_main_worktree,node_main_pty,node_main_snapshot,node_main_services,node_main_wizard toneBlue
class node_renderer_app,node_renderer_left,node_renderer_main,node_renderer_diff,node_renderer_terminal,node_renderer_right,node_renderer_stores toneAmber
class node_shared_models toneMint
```

## Components

### Main process

Electron backend: bootstrap, IPC, persistence, and services

- [Main entry](https://github.com/syv-ai/dash/blob/main/src/main/entry.ts): bootstrap · Starts Electron and wires app lifecycle · `src/main/entry.ts`
- [Window](https://github.com/syv-ai/dash/blob/main/src/main/window.ts): electron shell · Creates the main window and renderer bridge · `src/main/window.ts`
- [Preload](https://github.com/syv-ai/dash/blob/main/src/main/preload.ts): bridge · Exposes typed renderer API through contextBridge · `src/main/preload.ts`
- [IPC handlers](https://github.com/syv-ai/dash/blob/main/src/main/ipc/index.ts): typed IPC · Main seam for renderer requests and backend events · `src/main/ipc/index.ts`
- [Database](https://github.com/syv-ai/dash/blob/main/src/main/db/client.ts): sqlite repo · SQLite persistence via better-sqlite3 and Drizzle · `src/main/db/client.ts`
- [DB service](https://github.com/syv-ai/dash/blob/main/src/main/services/DatabaseService.ts): persistence service · Owns database access and app state writes · `src/main/services/DatabaseService.ts`
- [Git service](https://github.com/syv-ai/dash/blob/main/src/main/services/GitService.ts): vcs service · Status, diffs, staging, commits, blame, and PR helpers · `src/main/services/GitService.ts`
- [Worktrees](https://github.com/syv-ai/dash/blob/main/src/main/services/WorktreeService.ts): workspace service · Creates, claims, and pools per-task Git worktrees · `src/main/services/WorktreeService.ts`
- [PTY manager](https://github.com/syv-ai/dash/blob/main/src/main/services/ptyManager.ts): terminal backend · Runs and mirrors task terminals in the main process · `src/main/services/ptyManager.ts`
- [Snapshots](https://github.com/syv-ai/dash/blob/main/src/main/services/TerminalSnapshotService.ts): terminal state · Persists terminal sessions and restore snapshots · `src/main/services/TerminalSnapshotService.ts`
- [Background services](https://github.com/syv-ai/dash/blob/main/src/main/services/ServiceRunner.ts): runtime services · File watching, activity, ports, telemetry, update, and integrations · `src/main/services/ServiceRunner.ts`
- [Wizards](https://github.com/syv-ai/dash/blob/main/src/main/wizard/WizardOrchestrator.ts): onboarding orchestrator · Guided setup flows, especially ports onboarding · `src/main/wizard/WizardOrchestrator.ts`

### Renderer

React UI and local state

- [App shell](https://github.com/syv-ai/dash/blob/main/src/renderer/App.tsx): react root · Top-level UI, keyboard handling, layout, and modals · `src/renderer/App.tsx`
- [Left sidebar](https://github.com/syv-ai/dash/blob/main/src/renderer/components/leftSidebar/LeftSidebar.tsx): navigation UI · Project and task navigation with rotation controls · `src/renderer/components/leftSidebar/LeftSidebar.tsx`
- [Main content](https://github.com/syv-ai/dash/blob/main/src/renderer/components/MainContent.tsx): workspace UI · Project overview, task view, and change-centric screens · `src/renderer/components/MainContent.tsx`
- [Diff editor](https://github.com/syv-ai/dash/blob/main/src/renderer/components/diffEditor/DiffEditor.tsx): review UI · File diffs, editor, blame, and comments overlay · `src/renderer/components/diffEditor/DiffEditor.tsx`
- [Terminal UI](https://github.com/syv-ai/dash/blob/main/src/renderer/components/terminal/TerminalPane.tsx): terminal UI · Xterm-based shell panes and tabbed terminal sessions · `src/renderer/components/terminal/TerminalPane.tsx`
- [Right inspector](https://github.com/syv-ai/dash/blob/main/src/renderer/components/rightInspector/RightInspector.tsx): tooling UI · Ports, usage, and task tooling drawers · `src/renderer/components/rightInspector/RightInspector.tsx`
- [Stores](https://github.com/syv-ai/dash/blob/main/src/renderer/stores/projectsStore.ts): local state · Projects, tasks, settings, runtime, git, and comments state · `src/renderer/stores/projectsStore.ts`

### Shared

Types and protocols consumed by both processes

- [Shared models](https://github.com/syv-ai/dash/blob/main/src/shared/types.ts): domain types · Project, task, session, wizard, and protocol shapes · `src/shared/types.ts`

## Connections

- Main entry → Window: creates · Bootstraps the app window and lifecycle
- Window → Preload: exposes · Connects renderer to the preload bridge
- Preload → App shell: API to UI · Renderer consumes the exposed electron API
- Main entry → IPC handlers: registers · Installs all IPC handlers
- App shell → IPC handlers: requests · All backend interaction goes through typed IPC
- IPC handlers → DB service: database · Routes persistence operations to the DB service
- DB service → Database: reads/writes · Persists projects, tasks, and history
- IPC handlers → Git service: git · Exposes repository and diff operations
- IPC handlers → Worktrees: worktrees · Manages task worktree lifecycle
- IPC handlers → PTY manager: pty · Starts and controls terminal sessions
- PTY manager → Snapshots: snapshots · Persists and restores terminal state
- IPC handlers → Background services: services · Exposes background runtime capabilities
- IPC handlers → Wizards: wizards · Starts onboarding and setup flows
- Background services → Git service: uses · Background logic depends on git state
- Background services → PTY manager: watches · Tracks terminal and session activity
- Background services → Worktrees: coordinates · Connects worktrees with project/task setup
- App shell → Stores: state · UI reads and updates local store state
- App shell → Left sidebar: lays out · Renders the project/task sidebar
- App shell → Main content: lays out · Renders the main workspace content
- App shell → Right inspector: lays out · Renders inspectors and drawers
- Main content → Diff editor: opens · Diff and editor workflows live here
- Main content → Terminal UI: opens · Task shells and terminal panes live here
- Right inspector → Diff editor: supports · Ports and tooling drawers complement review flows
- Stores → Shared models: uses · Stores share the domain model and protocol shapes
- IPC handlers → Shared models: types · IPC schemas are defined against shared contracts
- Wizards → App shell: surfaces · Wizard flows appear as modals and toasts in the UI
- Background services → DB service: tracks · Background services consult persisted state