How syv-ai/dash works
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: index.ts IPC handlers · App.tsx App shell · ServiceRunner.ts Background services · MainContent.tsx Main content
Components 20
Main process
Electron backend: bootstrap, IPC, persistence, and services
- Main entry · Starts Electron and wires app lifecycle
src/main/entry.ts - Window · Creates the main window and renderer bridge
src/main/window.ts - Preload · Exposes typed renderer API through contextBridge
src/main/preload.ts - IPC handlers · Main seam for renderer requests and backend events
src/main/ipc/index.ts - Database · SQLite persistence via better-sqlite3 and Drizzle
src/main/db/client.ts - DB service · Owns database access and app state writes
src/main/services/DatabaseService.ts - Git service · Status, diffs, staging, commits, blame, and PR helpers
src/main/services/GitService.ts - Worktrees · Creates, claims, and pools per-task Git worktrees
src/main/services/WorktreeService.ts - PTY manager · Runs and mirrors task terminals in the main process
src/main/services/ptyManager.ts - Snapshots · Persists terminal sessions and restore snapshots
src/main/services/TerminalSnapshotService.ts - Background services · File watching, activity, ports, telemetry, update, and integrations
src/main/services/ServiceRunner.ts - Wizards · Guided setup flows, especially ports onboarding
src/main/wizard/WizardOrchestrator.ts
Renderer
React UI and local state
- App shell · Top-level UI, keyboard handling, layout, and modals
src/renderer/App.tsx - Left sidebar · Project and task navigation with rotation controls
src/renderer/components/leftSidebar/LeftSidebar.tsx - Main content · Project overview, task view, and change-centric screens
src/renderer/components/MainContent.tsx - Diff editor · File diffs, editor, blame, and comments overlay
src/renderer/components/diffEditor/DiffEditor.tsx - Terminal UI · Xterm-based shell panes and tabbed terminal sessions
src/renderer/components/terminal/TerminalPane.tsx - Right inspector · Ports, usage, and task tooling drawers
src/renderer/components/rightInspector/RightInspector.tsx - Stores · Projects, tasks, settings, runtime, git, and comments state
src/renderer/stores/projectsStore.ts
Shared
Types and protocols consumed by both processes
- Shared models · Project, task, session, wizard, and protocol shapes
src/shared/types.ts
Connections 27
- 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