# devroots-studio/selfhost-helper architecture

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

- Interactive diagram: https://gitdiagram.com/devroots-studio/selfhost-helper
- Repository: https://github.com/devroots-studio/selfhost-helper
- Video tour (about a minute): https://gitdiagram.com/devroots-studio/selfhost-helper/video

## Overview

SelfHost Helper is an Electron desktop cockpit for managing local development projects. Users organize projects on the dashboard, open a project workspace, then run and monitor its processes, inspect files and logs, edit/search code, use Git, and optionally expose a service through a tunnel. The renderer communicates with Electron services through the preload/IPC boundary; project state is persisted locally. README capabilities are included where the tree supports a subsystem, but their detailed wiring is not asserted where source excerpts were unavailable.

Main entry points: [`electron/ipc/handlers.js`](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/ipc/handlers.js) (IPC handlers), [`electron/preload.js`](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/preload.js) (Preload bridge), [`electron/services/projectsManager.js`](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/projectsManager.js) (Project manager), [`src/App.jsx`](https://github.com/devroots-studio/selfhost-helper/blob/main/src/App.jsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_electron["Electron main<br/>[main.js]"]
  node_preload["Preload bridge<br/>[preload.js]"]
  node_ipc["IPC handlers<br/>[handlers.js]"]
end

subgraph group_workspace["Project workspace"]
  node_app["React app<br/>[App.jsx]"]
  node_dashboard["Project dashboard<br/>[Dashboard.jsx]"]
  node_projectui["Project workspace<br/>[ProjectLayout.jsx]"]
  node_overview["Overview cockpit<br/>[OverviewView.jsx]"]
  node_resources["Resource view<br/>[ResourcesTab.jsx]"]
  node_tunnelui["Tunnel view<br/>[TunnelView.jsx]"]
end

subgraph group_lifecycle["Process lifecycle"]
  node_projects["Project manager<br/>[projectsManager.js]"]
  node_processes["Process tree<br/>[processTree.js]"]
  node_job["Native job control<br/>[index.js]"]
  node_stats["Stats service<br/>[statsService.js]"]
end

subgraph group_devtools["Developer tools"]
  node_editor["Editor and Git<br/>[EditorView.jsx]"]
  node_files["File watcher<br/>[filesWatcher.js]"]
  node_search["Project search<br/>[searchService.js]"]
  node_git["Git service<br/>[gitService.js]"]
  node_lsp["Language server<br/>[lspBridge.js]"]
end

subgraph group_integrations["Persistence and integrations"]
  node_tunnels["Tunnel manager<br/>[tunnelManager.js]"]
  node_database[("SQLite database<br/>[database.js]")]
  node_models["Project and category models<br/>[Project.js]"]
  node_backup["Backup service"]
end

node_developer(("Developer"))
node_cloudflare{{"Cloudflare Tunnel"}}
node_localprocess{{"Local project processes"}}

node_developer -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_projectui
node_dashboard -->|"requests projects"| node_preload
node_projectui -->|"invokes operations"| node_preload
node_preload -->|"dispatches IPC"| node_ipc
node_electron -->|"registers handlers"| node_ipc
node_ipc -->|"controls projects"| node_projects
node_projects -->|"reads and writes"| node_database
node_database -->|"persists records"| node_models
node_projects -->|"tracks and stops"| node_processes
node_projects -->|"controls jobs"| node_job
node_projects -->|"spawns and stops"| node_localprocess
node_projects -->|"starts telemetry"| node_stats
node_overview -->|"requests telemetry"| node_preload
node_resources -->|"requests resources"| node_preload
node_editor -->|"requests tools"| node_preload
node_ipc -->|"manages watching"| node_files
node_ipc -->|"runs search"| node_search
node_ipc -->|"runs Git actions"| node_git
node_ipc -->|"controls language server"| node_lsp
node_ipc -->|"starts and stops"| node_tunnels
node_tunnelui -->|"controls tunnels"| node_preload
node_tunnels -.->|"runs tunnel"| node_cloudflare
node_ipc -->|"imports configuration"| node_backup

click node_electron "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/main.js"
click node_preload "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/preload.js"
click node_ipc "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/ipc/handlers.js"
click node_app "https://github.com/devroots-studio/selfhost-helper/blob/main/src/App.jsx"
click node_dashboard "https://github.com/devroots-studio/selfhost-helper/blob/main/src/pages/Dashboard.jsx"
click node_projectui "https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/ProjectLayout.jsx"
click node_overview "https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/OverviewView.jsx"
click node_editor "https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/EditorView.jsx"
click node_resources "https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/ResourcesTab.jsx"
click node_tunnelui "https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/TunnelView.jsx"
click node_projects "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/projectsManager.js"
click node_processes "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/processTree.js"
click node_job "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/job/index.js"
click node_stats "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/statsService.js"
click node_files "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/filesWatcher.js"
click node_search "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/searchService.js"
click node_git "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/gitService.js"
click node_lsp "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/lspBridge.js"
click node_tunnels "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/tunnelManager.js"
click node_database "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/database.js"
click node_models "https://github.com/devroots-studio/selfhost-helper/blob/main/database/models/Project.js"
click node_backup "https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/configBackupService.js"

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_electron,node_preload,node_ipc toneBlue
class node_app,node_dashboard,node_projectui,node_overview,node_resources,node_tunnelui toneAmber
class node_projects,node_processes,node_job,node_stats toneMint
class node_editor,node_files,node_search,node_git,node_lsp toneRose
class node_tunnels,node_database,node_models,node_backup,node_developer,node_cloudflare,node_localprocess toneIndigo
```

## Components

### Desktop shell

- [Electron main](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/main.js): `electron/main.js`
- [Preload bridge](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/preload.js): `electron/preload.js`
- [IPC handlers](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/ipc/handlers.js): `electron/ipc/handlers.js`

### Project workspace

- [React app](https://github.com/devroots-studio/selfhost-helper/blob/main/src/App.jsx): `src/App.jsx`
- [Project dashboard](https://github.com/devroots-studio/selfhost-helper/blob/main/src/pages/Dashboard.jsx): `src/pages/Dashboard.jsx`
- [Project workspace](https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/ProjectLayout.jsx): `src/components/ProjectLayout.jsx`
- [Overview cockpit](https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/OverviewView.jsx): `src/components/OverviewView.jsx`
- [Resource view](https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/ResourcesTab.jsx): `src/components/ResourcesTab.jsx`
- [Tunnel view](https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/TunnelView.jsx): `src/components/TunnelView.jsx`

### Process lifecycle

- [Project manager](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/projectsManager.js): `electron/services/projectsManager.js`
- [Process tree](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/processTree.js): `electron/services/processTree.js`
- [Native job control](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/job/index.js): `electron/job/index.js`
- [Stats service](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/statsService.js): `electron/services/statsService.js`

### Developer tools

- [Editor and Git](https://github.com/devroots-studio/selfhost-helper/blob/main/src/components/EditorView.jsx): `src/components/EditorView.jsx`
- [File watcher](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/filesWatcher.js): `electron/services/filesWatcher.js`
- [Project search](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/searchService.js): `electron/services/searchService.js`
- [Git service](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/gitService.js): `electron/services/gitService.js`
- [Language server](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/lspBridge.js): `electron/services/lspBridge.js`

### Persistence and integrations

- [Tunnel manager](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/tunnelManager.js): `electron/services/tunnelManager.js`
- [SQLite database](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/database.js): `electron/services/database.js`
- [Project and category models](https://github.com/devroots-studio/selfhost-helper/blob/main/database/models/Project.js): `database/models/Project.js`
- [Backup service](https://github.com/devroots-studio/selfhost-helper/blob/main/electron/services/configBackupService.js): `electron/services/configBackupService.js`

### Other components

- **Developer**
- **Cloudflare Tunnel**
- **Local project processes**

## Connections

- Developer → React app: uses
- React app → Project dashboard: routes to
- React app → Project workspace: routes to
- Project dashboard → Preload bridge: requests projects
- Project workspace → Preload bridge: invokes operations
- Preload bridge → IPC handlers: dispatches IPC
- Electron main → IPC handlers: registers handlers
- IPC handlers → Project manager: controls projects
- Project manager → SQLite database: reads and writes
- SQLite database → Project and category models: persists records
- Project manager → Process tree: tracks and stops
- Project manager → Native job control: controls jobs
- Project manager → Local project processes: spawns and stops
- Project manager → Stats service: starts telemetry
- Overview cockpit → Preload bridge: requests telemetry
- Resource view → Preload bridge: requests resources
- Editor and Git → Preload bridge: requests tools
- IPC handlers → File watcher: manages watching
- IPC handlers → Project search: runs search
- IPC handlers → Git service: runs Git actions
- IPC handlers → Language server: controls language server
- IPC handlers → Tunnel manager: starts and stops
- Tunnel view → Preload bridge: controls tunnels
- Tunnel manager → Cloudflare Tunnel: runs tunnel
- IPC handlers → Backup service: imports configuration