chore: remove unused desktop app, cloud deployment infra, and monitoring stack
Deletes desktop/ (Electron wrapper), deployments/ (Helm/Kustomize/ Terraform/CI for cloud deploy), and monitoring/ (Prometheus + Grafana stack) along with DESKTOP.md, DEPLOYMENT.md, docker-compose.full.yml, their npm scripts, and every dangling reference across README, ARCHITECTURE, INSTALL, SETUP, docs/, and the repeated per-file MODULE_GUIDE "Observability" boilerplate comment. The GET /api/metrics endpoint itself is untouched — it's the dashboard's own route, not part of the removed monitoring stack.
This commit is contained in:
+2
-391
@@ -35,35 +35,13 @@ Architectural overview and technical reference for the Agent Dashboard system, c
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -87,7 +65,6 @@ Architectural overview and technical reference for the Agent Dashboard system, c
|
||||
- [Update Notifier Subsystem](#update-notifier-subsystem)
|
||||
- [Tabby Companion Subsystem](#tabby-companion-subsystem)
|
||||
- [VS Code Extension Architecture](#vs-code-extension-architecture)
|
||||
- [Desktop App Architecture (macOS & Windows / Electron)](#desktop-app-architecture-macos--windows--electron)
|
||||
- [Security Considerations](#security-considerations)
|
||||
- [Performance Characteristics](#performance-characteristics)
|
||||
- [Deployment Modes](#deployment-modes)
|
||||
@@ -348,8 +325,7 @@ graph TD
|
||||
| `routes/agents.js` | CRUD with status/session_id filtering. PATCH broadcasts `agent_updated`. Agent-list responses (`GET /api/agents`, `GET /api/sessions/:id/agents`) attach a per-agent `cost` via `pricing.attachAgentCosts` — each subagent's OWN cost, computed from its `metadata.tokens` at current rates (main agents get 0; their cost is the session total), so a subagent card shows only what that subagent spent rather than the session total |
|
||||
| `routes/events.js` | Read-only event listing with session_id filter and pagination |
|
||||
| `routes/stats.js` | Single aggregate query returning total/active counts + status distributions |
|
||||
| `routes/metrics.js` | Prometheus / OpenMetrics text-exposition endpoint (`GET /api/metrics`) — re-exposes the dashboard's live counters (sessions/agents by status, event + token totals, connected WebSocket clients, configured remote sources, process uptime/RSS, build version) in the v0.0.4 text format for scraping into Prometheus / Grafana. Read-only; reads the same `db.js` prepared statements the REST API uses, so numbers match the UI. Status series are enumerated so a gauge never drops out at zero. Mounted under `/api`, so it sits behind the Host-header (DNS-rebinding) guard and the optional `DASHBOARD_TOKEN` guard — a non-loopback scraper needs `DASHBOARD_ALLOWED_HOSTS` (+ token if set). A turnkey Prometheus + Grafana stack with four auto-provisioned dashboards lives in `monitoring/` (`npm run monitoring:up` or `npm run docker:full:up`) |
|
||||
| `monitoring/` | Optional npm-managed or Docker Compose Prometheus + Grafana stack that scrapes `GET /api/metrics`. Ships four Grafana dashboards (`ccam-overview`, `ccam-sessions-agents`, `ccam-tokens-events`, `ccam-platform`), recording rules (`prometheus/ccam-rules.yml`), a Prometheus 3.x-compatible static HTML console (`prometheus/consoles/index.html`), and lifecycle scripts (`monitoring:install`, `monitoring:up`, `monitoring:verify`). See [`monitoring/README.md`](./monitoring/README.md) |
|
||||
| `routes/metrics.js` | Prometheus / OpenMetrics text-exposition endpoint (`GET /api/metrics`) — re-exposes the dashboard's live counters (sessions/agents by status, event + token totals, connected WebSocket clients, configured remote sources, process uptime/RSS, build version) in the v0.0.4 text format for scraping into Prometheus / Grafana. Read-only; reads the same `db.js` prepared statements the REST API uses, so numbers match the UI. Status series are enumerated so a gauge never drops out at zero. Mounted under `/api`, so it sits behind the Host-header (DNS-rebinding) guard and the optional `DASHBOARD_TOKEN` guard — a non-loopback scraper needs `DASHBOARD_ALLOWED_HOSTS` (+ token if set) |
|
||||
| `routes/analytics.js` | Extended analytics — token totals, tool usage counts, daily event/session trends, agent type distribution. The client-side analytics heatmap grid is aligned to a Sunday start for correct day-of-week positioning |
|
||||
| `routes/pricing.js` | Model pricing CRUD (list/upsert/delete) and per-session / global cost calculation with pattern-based model matching. `PUT /api/pricing` upserts a rule and accepts optional time-limited **introductory** rates (`intro_*_per_mtok` + `intro_until`): usage on/before the cutoff date prices at the intro rate, after it at the standard rate — the calculator picks the effective rate per usage day (`ratesForBucket`), so a promo like Sonnet 5's launch discount is correct before AND after the cutoff, retroactively. Intro columns are written only when the caller sends them (a standard-rate edit never disturbs a promo). Cost is computed per token bucket — keyed by (model, speed, inference_geo, service_tier) — applying fast-mode premium, US data-residency (1.1x), and Batch (0.5x) modifiers, the 5m/1h cache-write split, plus server-tool surcharges (web search $10/1k; code execution estimated by container-time with the monthly free-hours allowance; web fetch free). `attachAgentCosts`/`agentOwnCost` reuse the same calculator to price each agent's `metadata.tokens` for the per-agent `cost` on agent-list responses. Feature rates + modifier math live in `lib/pricing-constants.js`; usage normalization in `lib/token-usage.js` |
|
||||
| `routes/settings.js` | System info (DB size, hook status, server uptime, transcript cache stats), data export as one versioned JSON bundle and matching import/restore (`POST /api/settings/import` via `server/lib/data-transfer.js` — idempotent, session-atomic, non-destructive; consolidates machines), session cleanup (abandon stale, purge old), clear all data (including the fired-alert feed and webhook delivery log; alert *rules* and webhook *targets* are preserved as user configuration), reset pricing, reinstall hooks |
|
||||
@@ -2011,7 +1987,7 @@ Cache versioning is controlled by the `CACHE_NAME` constant (`dashboard-v2`). On
|
||||
|
||||
`client/src/main.tsx` snapshots `navigator.serviceWorker.controller` before registration and listens for `controllerchange`: when a new SW activates on an already-controlled page, it reloads exactly once so the page picks up the new asset URLs without a hard refresh. The first install (no previous controller) does **not** reload.
|
||||
|
||||
These behaviors are reinforced by explicit `Cache-Control` headers from the production Express static middleware in `server/index.js`: `immutable, max-age=31536000` for `/assets/*`; `no-cache, must-revalidate` for `index.html`, `sw.js`, and `manifest.json`; a short revalidation window for other static files. The SPA fallback `sendFile` sends the same `no-cache` header. The native desktop shell (macOS and Windows) loads the dashboard from this same in-process server (`NODE_ENV=production`), so it inherits the policy automatically.
|
||||
These behaviors are reinforced by explicit `Cache-Control` headers from the production Express static middleware in `server/index.js`: `immutable, max-age=31536000` for `/assets/*`; `no-cache, must-revalidate` for `index.html`, `sw.js`, and `manifest.json`; a short revalidation window for other static files. The SPA fallback `sendFile` sends the same `no-cache` header.
|
||||
|
||||
---
|
||||
|
||||
@@ -2308,299 +2284,6 @@ For the extension source code, refer to the [vscode-extension/](./vscode-extensi
|
||||
|
||||
---
|
||||
|
||||
## Desktop App Architecture (macOS & Windows / Electron)
|
||||
|
||||
The `desktop/` workspace ships the dashboard as a **native desktop app** for **macOS** (`Claude Code Monitor.app`, distributed as a `.dmg`) **and Windows** (`Claude Code Monitor.exe`, distributed as an NSIS installer plus a no-install portable build). It is an Electron shell that **embeds the existing Express server in-process** and renders the already-built React client in a `BrowserWindow`. The desktop app does not reimplement the dashboard -- it `require()`s `server/index.js` directly, in the same Node runtime as the Electron main process, and points a Chromium window at it.
|
||||
|
||||
For the user-facing guide (download, install, Gatekeeper / SmartScreen, tray menu, auto-start), see [DESKTOP.md](./DESKTOP.md). For the full contributor/architecture reference -- including build performance, code signing, notarization, and CI details -- see [desktop/README.md](./desktop/README.md).
|
||||
|
||||
### Workspace Position
|
||||
|
||||
`desktop/` is a **sibling workspace**, not an npm-workspaces conversion. It has its own `package.json`, its own `node_modules`, and its own TypeScript toolchain. It pins **Electron 35** (bundled Node 22.16). It consumes the rest of the repo as plain files and touches no other workspace's runtime behavior.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph repo["Claude-Code-Agent-Monitor (repo root)"]
|
||||
server["server/<br/>Express API · SQLite · WebSocket"]
|
||||
client["client/<br/>React + Vite SPA"]
|
||||
scripts["scripts/<br/>hook installer/handler, import, seed"]
|
||||
mcp["mcp/<br/>local MCP server"]
|
||||
vscode["vscode-extension/"]
|
||||
desktop["desktop/<br/>Electron shell (sibling workspace)"]
|
||||
end
|
||||
|
||||
desktop -->|"require() in-process"| server
|
||||
desktop -->|"loads built SPA from"| client
|
||||
desktop -->|"auto-installs hooks via"| scripts
|
||||
server -->|"serves static"| client
|
||||
|
||||
style desktop fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style server fill:#238636,stroke:#196c2e,color:#fff
|
||||
```
|
||||
|
||||
The **only** change outside `desktop/` is a behavior-preserving refactor of `server/index.js` (see [Background Services & Hook Bootstrap](#background-services--hook-bootstrap-1) below). `client/`, `scripts/`, `mcp/`, and `vscode-extension/` are untouched.
|
||||
|
||||
### Process Model
|
||||
|
||||
Electron runs a **main process** (Node.js) and one or more **renderer processes** (Chromium). In this app:
|
||||
|
||||
- The **main process** hosts the embedded Express server _and_ manages the window, tray, and menus. There is **no child process and no IPC** for the server -- it runs inside the main process's own event loop.
|
||||
- The **renderer** is plain Chromium loading `http://127.0.0.1:<port>` -- exactly the same origin a normal browser would use. `preload.ts` is intentionally empty (`contextIsolation: true`, `nodeIntegration: false`, `webSecurity: true`), so the renderer has **zero privileged surface**.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph main["Electron Main Process (Node 22 / Electron 35)"]
|
||||
boot["main.ts<br/>lifecycle"]
|
||||
host["server-host.ts<br/>embedded server"]
|
||||
express["server/index.js<br/>Express + WS + SQLite"]
|
||||
tray["tray.ts"]
|
||||
menu["menu.ts"]
|
||||
host --> express
|
||||
boot --> host
|
||||
boot --> tray
|
||||
boot --> menu
|
||||
end
|
||||
|
||||
subgraph renderer["Renderer Process (Chromium)"]
|
||||
win["BrowserWindow<br/>React dashboard"]
|
||||
preload["preload.ts<br/>(empty -- no bridge)"]
|
||||
end
|
||||
|
||||
express -->|"http + ws on 127.0.0.1:port"| win
|
||||
win -.->|loads| preload
|
||||
|
||||
hooks["Claude Code hooks<br/>(separate node processes)"] -->|"POST /api/hooks/event"| express
|
||||
|
||||
style main fill:#0d1117,stroke:#30363d,color:#e6edf3
|
||||
style renderer fill:#161b22,stroke:#30363d,color:#e6edf3
|
||||
```
|
||||
|
||||
### In-Process Server Hosting
|
||||
|
||||
`server-host.ts` is the **only file** that imports `server/index.js`. The dashboard server already exports `{ createApp, startServer, startBackgroundServices }` and serves the built React client (`client/dist`) as static assets in production -- so the host imports that module directly, with no child process, no IPC, and no port marshalling.
|
||||
|
||||
| Component | Responsibility |
|
||||
| --- | --- |
|
||||
| **`main.ts`** | Main-process entry. Single-instance lock, app menu + tray wiring, dashboard window, `Restart Server`, lifecycle (`window-all-closed`, `before-quit`). |
|
||||
| **`server-host.ts`** | In-process Express boot: port discovery, adoption, `better-sqlite3` ABI patch, `startBackgroundServices()` + hook bootstrap, clean DB close. Returns a `ServerHandle`. |
|
||||
| **`window.ts`** | `BrowserWindow` with persisted geometry (`userData/window-state.json`). External links open in the system browser. Sets the window/taskbar `icon` to the colored app logo (`assets/icon.ico` on Windows, `icon.png` elsewhere) so an unpackaged `desktop:dev` run no longer shows the generic Electron icon. |
|
||||
| **`menu.ts` / `tray.ts`** | Native application menu and menu-bar / notification-area (tray) icon. `tray.ts` selects a platform tray image — a macOS template glyph that the OS tints for the menu bar, or the colored `assets/icon.ico` for the Windows notification area (a black template would vanish on the dark taskbar). Tray uses a single-click dropdown (left or right) with a **live status snapshot** queried straight from SQLite at click time — server port, active sessions, working agents, events today — followed by *Open Dashboard*, *Open in Browser*, *Restart Server*, *Show Logs*, *Open at Login* (toggle), and *Quit*. The menu is rebuilt on each open so every value stays current. Snapshot rows are enabled and click-to-open-dashboard rather than disabled (which the OS dims). The application menu's *File ▸ Open Dashboard* (⌘1) is **macOS-only** — there the global menu bar persists after the window hides; on Windows/Linux the window-attached menu can't reopen a hidden window, so reopening is the tray's job. `focusOrCreateWindow` calls `show()` unconditionally so the tray reliably raises a backgrounded/minimized window (a bare `focus()` on Windows often only flashes the taskbar). |
|
||||
| **`login-item.ts`** | Auto-start-at-login toggle through Electron's first-party `app.setLoginItemSettings` API on every platform. On macOS it drives the modern `SMAppService` Login Items (not a `LaunchAgent` plist); on Windows it writes a per-user `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` entry. Login launches are tagged with a `--ccam-hidden` arg so the app can stay tray-only at startup — Windows has no `wasOpenedAtLogin` signal, so the arg is the cross-platform detection mechanism. |
|
||||
| **`shell-path.ts`** | (macOS) Recovers the user's login-shell `PATH` at startup and merges it onto `process.env.PATH`, so the embedded server (and the `claude` CLI it spawns) is not limited to launchd's minimal `PATH`. On Windows the process already inherits the full user `PATH`, so no recovery is needed. |
|
||||
| **`logger.ts`** | File logger to `~/Library/Logs/Claude Code Monitor/desktop.log` (macOS) or `%APPDATA%\Claude Code Monitor\logs\desktop.log` (Windows) -- the main process has no console when launched from Finder / Explorer. |
|
||||
| **`constants.ts`** | Shared identifiers, including the `APP_ID` (`com.vn.smartgift.ccam.desktop`) that `main.ts` sets as the Windows AppUserModelId. |
|
||||
|
||||
`server-host.ts` resolves the directory containing the bundled `server/` and `client/dist/` via `resolveAppRoot()`: `process.resourcesPath/app` when packaged, or the repo root (one directory up from `desktop/`) in development.
|
||||
|
||||
The `ServerHandle` returned to `main.ts`:
|
||||
|
||||
```ts
|
||||
interface ServerHandle {
|
||||
url: string; // e.g. "http://127.0.0.1:4820"
|
||||
port: number;
|
||||
ownedByUs: boolean; // false when an existing server was adopted
|
||||
stop: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### Port Discovery & Adoption
|
||||
|
||||
On startup `server-host.ts` picks a port, then either adopts an already-healthy server or boots its own. **Adoption** -- `probePort()` connects to `:4820`, then checks that the listener answers `GET /api/health` with `{ status: "ok" }`. If a healthy dashboard server is already running there (e.g. the user ran `npm start` in a terminal), the desktop app **adopts** it rather than double-binding -- no SQLite contention. An adopted server is not owned by the app, so quitting the app leaves it running.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start["startEmbeddedServer()"] --> forced{"CCAM_DESKTOP_BIND_PORT set?"}
|
||||
forced -->|yes| bind["bind exactly that port<br/>(no adoption, no fallback)"]
|
||||
forced -->|no| adopt{"healthy server<br/>already on :4820?"}
|
||||
adopt -->|yes| reuse["adopt it<br/>ownedByUs = false"]
|
||||
adopt -->|no| pick["pickFreePort()"]
|
||||
|
||||
pick --> p1{":4820 free?"}
|
||||
p1 -->|yes| use4820["use 4820"]
|
||||
p1 -->|no| p2{"any of<br/>:4821–:4829 free?"}
|
||||
p2 -->|yes| usefb["use that"]
|
||||
p2 -->|no| p3{"any of<br/>:49152–:49500 free?"}
|
||||
p3 -->|yes| userand["use that"]
|
||||
p3 -->|no| fail["throw — no free port"]
|
||||
|
||||
bind --> bootsrv["createApp() + startServer()"]
|
||||
use4820 --> bootsrv
|
||||
usefb --> bootsrv
|
||||
userand --> bootsrv
|
||||
bootsrv --> healthy["waitForHealthy()<br/>poll /api/health ≤ 30s"]
|
||||
healthy --> bg["bootstrapOwnedServer()"]
|
||||
bg --> handle["ServerHandle ownedByUs = true"]
|
||||
reuse --> handleR["ServerHandle ownedByUs = false"]
|
||||
|
||||
style reuse fill:#9e6a03,stroke:#7d5300,color:#fff
|
||||
style fail fill:#da3633,stroke:#b62324,color:#fff
|
||||
```
|
||||
|
||||
Port preference order is **4820 → 4821–4829 → a random port in 49152–49500**. Two environment overrides exist primarily for testing: `CCAM_DESKTOP_BIND_PORT` binds an exact port (disabling adoption and fallback, used by the smoke test), and `CCAM_DESKTOP_NO_ADOPT=1` always starts a fresh server. Before `require()`ing the server module, the host sets `NODE_ENV=production`, `DASHBOARD_PORT=<port>`, and `DASHBOARD_DATA_DIR=<userData>/data` (see [Writable Data Directory](#writable-data-directory) below) so the server reads them from `process.env`.
|
||||
|
||||
### Writable Data Directory
|
||||
|
||||
A packaged install directory is **read-only** in practice: on macOS a `.app` bundle installed under `/Applications`, code-signed, or run through **app translocation** cannot write to `Resources/app/`, and on Windows the NSIS install dir under `%ProgramFiles%` (or the read-only mount a portable build runs from) is no place for mutable state. The dashboard's SQLite database and the VAPID keypair (`server/lib/push.js`) are writable state, so they must not live inside the bundle / install dir. Before booting the embedded server, `server-host.ts` creates `app.getPath('userData')/data` and points the server at it via the `DASHBOARD_DATA_DIR` environment variable:
|
||||
|
||||
- `server/db.js` honors `DASHBOARD_DATA_DIR` for the SQLite file.
|
||||
- `server/lib/push.js` honors it for the persisted VAPID keys.
|
||||
|
||||
The resulting per-user location is `~/Library/Application Support/Claude Code Monitor/data/` on macOS and `%APPDATA%\Claude Code Monitor\data\` on Windows. Because this lives outside the bundle / install dir, imported history and persisted events **survive an app reinstall or update** (the Windows NSIS uninstaller keeps this data by default). Without this, writing a database into the read-only install location failed on a packaged build and broke History Import and event persistence.
|
||||
|
||||
The standalone `node server/index.js` path is **unaffected**: `DASHBOARD_DATA_DIR` is unset there, and `server-host.ts` only sets it when it is not already defined -- so `server/db.js` falls back to its usual repo-relative default.
|
||||
|
||||
### Shell `PATH` Recovery (macOS)
|
||||
|
||||
This step is **macOS-only**. A macOS app launched from Finder, the Dock, or Login Items auto-start is spawned by `launchd`, which hands it a **minimal `PATH`** (roughly `/usr/bin:/bin:/usr/sbin:/sbin`) and does **not** source the user's shell profile. The dashboard's "Run Claude" feature (`server/routes/run.js`, `server/lib/run-spawner.js`) spawns the `claude` CLI, which is almost always installed somewhere only the shell `PATH` knows about (`/opt/homebrew/bin`, `~/.local/bin`, `~/.claude/local`, a Node version-manager's bin dir). Under launchd's `PATH`, `claude` cannot be resolved or spawned.
|
||||
|
||||
`shell-path.ts` repairs this **before the server boots**: at startup it runs the user's login+interactive shell once (`$SHELL -ilc`, so `.zprofile`/`.zshrc` are sourced), captures the resulting `PATH` between sentinel markers, and merges it -- plus a fallback list of common CLI install directories -- onto `process.env.PATH`. The merge is order-preserving and deduplicated, so it is idempotent. Because the embedded server runs in the same process, it and every `claude` it spawns inherit the corrected `PATH`. (A `claude` shell _alias_ or _function_ still cannot be spawned -- only a real executable on the `PATH` can.)
|
||||
|
||||
On **Windows** there is no equivalent step: a process launched from Explorer, the Start menu, or the `HKCU\…\Run` startup entry already inherits the full user `PATH`, so the embedded server can resolve `claude` directly.
|
||||
|
||||
### `better-sqlite3` Native-Module Handling
|
||||
|
||||
`better-sqlite3` is the only **native** module in the dependency tree, and a native module must be compiled against the exact Node ABI it runs on. The repo-root copy is built for the **system Node** (so `npm run test:server` works for contributors); Electron ships its **own Node ABI**.
|
||||
|
||||
The desktop workspace solves this without disturbing the root install: the desktop workspace has its own `better-sqlite3`, rebuilt for Electron's Node ABI by `electron-builder install-app-deps` (run in its `postinstall`). `server-host.ts` then installs a one-time, **process-local** patch to `Module._resolveFilename` that redirects `require("better-sqlite3")` -- from anywhere in the embedded server -- to that ABI-correct copy.
|
||||
|
||||
Desktop setup is **guarded** so a missing or unbuilt binary never escapes as a raw node-gyp trace or a runtime crash: `desktop/scripts/preflight.js` (shared by `install.js` and `prebuild.js`) verifies the Electron-ABI binary exists and, when it doesn't, prints actionable, copy-pasteable setup help -- the per-OS C++ toolchain prerequisites (or a no-toolchain alternative that fetches Electron's prebuilt binary directly) -- before exiting non-zero. `desktop:install` runs this on install; the `prebuild` gate enforces it before every `desktop:*` build, turning a would-be runtime failure into a build-time error.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph desk["desktop/node_modules"]
|
||||
d1["better-sqlite3<br/>rebuilt for Electron's ABI<br/>(electron-builder install-app-deps)"]
|
||||
end
|
||||
subgraph root["node_modules (repo root)"]
|
||||
r1["better-sqlite3<br/>built for system Node<br/>(used by npm run test:server)"]
|
||||
end
|
||||
|
||||
patch["ensureNativeModulesPatched()<br/>overrides Module._resolveFilename"]
|
||||
srv["server/db.js<br/>require('better-sqlite3')"]
|
||||
|
||||
srv -->|"request intercepted"| patch
|
||||
patch -->|"redirected to"| d1
|
||||
patch -.->|"everything else<br/>passes through"| root
|
||||
|
||||
style d1 fill:#238636,stroke:#196c2e,color:#fff
|
||||
style patch fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
```
|
||||
|
||||
- The patch is installed exactly once, **before** `server/index.js` is `require()`d, and rewrites _only_ `require("better-sqlite3")` -- every other module resolves normally.
|
||||
- `electron-builder.yml` therefore **excludes** the root `better-sqlite3` from the bundle (it would trip `@electron/universal`'s identical-file detector) and `asarUnpack`s the desktop copy (native `.node` files cannot live inside an `asar` archive).
|
||||
- The `compat-sqlite` (`node:sqlite`) fallback remains a safety net -- one reason the desktop app pins **Electron 35**, whose bundled Node 22.16 has `node:sqlite`.
|
||||
|
||||
### Background Services & Hook Bootstrap
|
||||
|
||||
`node server/index.js` runs its production bootstrap from an `if (require.main === module)` block. Because the desktop app **`require()`s** that module, the block never fires -- so the bootstrap was extracted into an exported `startBackgroundServices()` that both paths call. This is a **behavior-preserving refactor** of `server/index.js`: the standalone server path is functionally unchanged.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph standalone["node server/index.js"]
|
||||
s1["require.main === module"] --> s2["startBackgroundServices()"]
|
||||
end
|
||||
subgraph desktopapp["desktop app"]
|
||||
d1["server-host.ts<br/>bootstrapOwnedServer()"] --> d2["startBackgroundServices()"]
|
||||
d1 --> d3["installHooks()"]
|
||||
end
|
||||
|
||||
d2 --> svc
|
||||
s2 --> svc
|
||||
subgraph svc["Background services"]
|
||||
u["update scheduler"]
|
||||
w["cc-watcher (Claude config watcher)"]
|
||||
r["orphaned-run reconciliation"]
|
||||
end
|
||||
|
||||
style d1 fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
```
|
||||
|
||||
`bootstrapOwnedServer()` runs **once** -- guarded by a module-level flag so a `Restart Server` does not double-register schedulers or watchers -- and:
|
||||
|
||||
1. Calls `startBackgroundServices()` -- the update scheduler, the `cc-watcher` config watcher, and one-time orphaned-run reconciliation.
|
||||
2. Calls `installHooks()` -- writes the Claude Code hook configuration to `~/.claude/settings.json`, so an install-only user (DMG on macOS, `.exe` on Windows) gets events flowing without ever running `npm run install-hooks` from a checkout.
|
||||
|
||||
It runs only when the server is **owned** by the app -- an adopted server has already done its own bootstrap.
|
||||
|
||||
### App Lifecycle
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant OS as macOS / Windows
|
||||
participant Main as main.ts
|
||||
participant Host as server-host.ts
|
||||
participant Srv as server/index.js
|
||||
participant UI as BrowserWindow
|
||||
|
||||
OS->>Main: launch app
|
||||
Main->>Main: setAppUserModelId (win32) · requestSingleInstanceLock()
|
||||
alt lock not acquired
|
||||
Main->>OS: exit(0) — focus existing instance
|
||||
end
|
||||
Main->>Host: ensureUserPath() — recover login-shell PATH (macOS only)
|
||||
Main->>Host: startEmbeddedServer()
|
||||
Host->>Host: probe :4820 — adopt if a healthy server answers
|
||||
alt no server to adopt
|
||||
Host->>Host: pickFreePort() · set DASHBOARD_DATA_DIR · patch better-sqlite3 ABI
|
||||
Host->>Srv: require() · createApp() · startServer(port)
|
||||
Host->>Srv: waitForHealthy() — poll /api/health ≤ 30s
|
||||
Host->>Srv: bootstrapOwnedServer() — schedulers, cc-watcher, install hooks
|
||||
end
|
||||
Host-->>Main: ServerHandle { url, port, ownedByUs, stop }
|
||||
Main->>Main: installApplicationMenu() · createTray()
|
||||
alt launched at login (--ccam-hidden / wasOpenedAtLogin)
|
||||
Main->>OS: stay tray-only, hide dock (macOS)
|
||||
else normal launch
|
||||
Main->>UI: createDashboardWindow(url)
|
||||
UI->>Srv: GET http://127.0.0.1:port
|
||||
end
|
||||
Note over Main: window "close" → hide (server keeps running)
|
||||
Note over Main: ⌘Q / Ctrl+Q → confirm (second press bypasses)
|
||||
Note over Main: before-quit → stop owned server + closeEmbeddedDatabase()
|
||||
```
|
||||
|
||||
| Event | Behavior |
|
||||
| --- | --- |
|
||||
| **Second launch** | `requestSingleInstanceLock()` (enabled on **every platform**) fails -- the new process exits and the existing window is focused. |
|
||||
| **Window close** | Intercepted -- the window **hides** (`hide()`); the server and tray keep running. |
|
||||
| **`window-all-closed`** | App stays alive in tray-only mode (the handler is intentionally a no-op). |
|
||||
| **Launched at login** | The dashboard window is **not** shown -- only the tray icon. Detected via macOS `wasOpenedAtLogin` (dock hidden, `openAsHidden`) or, on Windows, the `--ccam-hidden` arg written into the `HKCU\…\Run` startup command. |
|
||||
| **Quit shortcut** | ⌘Q (macOS) / Ctrl+Q (Windows) shows a confirmation dialog; a second press bypasses it. |
|
||||
| **`before-quit`** | If the server is owned: stop the HTTP server, then `closeEmbeddedDatabase()` for a clean WAL checkpoint, then `app.exit(0)`. The DB handle is closed here -- never on `Restart Server`, where the cached `server/db.js` singleton must stay usable. |
|
||||
|
||||
### Packaged App Layout
|
||||
|
||||
`electron-builder` produces `Claude Code Monitor.app` on macOS and `Claude Code Monitor.exe` (NSIS installer + portable) on Windows. On both platforms the Electron main-process code is compiled (`tsc` → `out/`) and packed into `app.asar`; the rest of the repo is shipped as **`extraResources`** -- plain files under the bundle's `Resources/app/` (macOS) or the install dir's `resources\app\` (Windows). The internal layout is the same shape on both:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
appbundle["Claude Code Monitor.app (macOS)<br/>Claude Code Monitor install dir (Windows)"]
|
||||
appbundle --> contents["Contents/ (macOS)<br/>install root (Windows)"]
|
||||
contents --> macos["MacOS/ — Electron binary (macOS)<br/>Claude Code Monitor.exe (Windows)"]
|
||||
contents --> res["Resources/ (macOS)<br/>resources\ (Windows)"]
|
||||
res --> asar["app.asar<br/>(compiled out/**, package.json)"]
|
||||
res --> unpacked["app.asar.unpacked/<br/>node_modules/better-sqlite3 (.node)"]
|
||||
res --> appdir["app/"]
|
||||
appdir --> a1["server/ — Express server (no tests)"]
|
||||
appdir --> a2["client/dist/ — built React SPA"]
|
||||
appdir --> a3["scripts/ — hook-handler, install-hooks"]
|
||||
appdir --> a4["node_modules/ — server runtime deps"]
|
||||
appdir --> a5["package.json"]
|
||||
|
||||
style asar fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style appdir fill:#238636,stroke:#196c2e,color:#fff
|
||||
```
|
||||
|
||||
At runtime `server-host.ts` resolves this root as `process.resourcesPath/app` when packaged, on both platforms. Everything under the packaged `app/` is **read-only** on a packaged, signed, or app-translocated macOS bundle and on a Windows install under `%ProgramFiles%` (or a portable build's mount) -- so all writable state (the SQLite database, VAPID keys) lives in the per-user data dir (`~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows), **never inside the bundle / install dir** (see [Writable Data Directory](#writable-data-directory)).
|
||||
|
||||
On macOS `electron-builder` produces **two per-architecture DMGs** — one `arm64` (Apple Silicon), one `x64` (Intel) — via `--mac --arm64 --x64` (not a merged universal binary; the release ships both), ad-hoc signed by default so anyone can build a working `.dmg` without a paid Apple Developer account; real Developer ID signing and notarization are opt-in via environment variables (`CSC_LINK`, `APPLE_ID`, etc.). On Windows it produces an **NSIS installer `.exe`** and a **no-install portable `.exe`** (both x64), using `assets/icon.ico` (generated from the source PNG by `desktop/scripts/build-win-icon.ps1`) as the application and tray icon. **`electron-builder` packages for the host OS** -- DMGs build on macOS, Windows `.exe`s build on Windows -- so the two artifacts come from two CI jobs (see below). The `desktop/scripts/prebuild.js` guard also **self-heals** a `better-sqlite3` native binary that a prior cross-arch DMG build (`electron-builder --mac --x64/--arm64`) left compiled for the wrong CPU architecture -- it detects the mismatch via `file` and re-runs `electron-builder install-app-deps`, so `desktop:dev` and `desktop:test` do not fail with `ERR_DLOPEN_FAILED`; on Windows it shells the `.cmd` shims for `npm`/`npx`. CI runs a path-filtered `🍎 macOS Desktop (DMG)` job on `macos-latest` (artifact `ClaudeCodeMonitor-dmg`) and a `🪟 Windows Desktop (EXE)` job on `windows-latest` (artifact `ClaudeCodeMonitor-win`); the release attaches both. See [`desktop/README.md`](./desktop/README.md) for the full build pipeline, build-performance notes, and signing details.
|
||||
|
||||
### Relation to Standalone Deployment
|
||||
|
||||
The desktop app is a fourth deployment mode alongside Development, Production, and Container (see [Deployment Modes](#deployment-modes)). The data path is **identical to the standalone Production path** -- Claude Code hooks `POST /api/hooks/event` to the embedded Express server, which writes to SQLite and broadcasts over WebSocket to the renderer. The only structural difference is that the server runs inside the Electron main process instead of a standalone `node server/index.js`, and the renderer is a `BrowserWindow` rather than a browser tab pointed at the same origin.
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
| Area | Approach |
|
||||
@@ -2687,26 +2370,6 @@ graph LR
|
||||
| **File watching** | `node --watch` + Vite HMR | None |
|
||||
| **Source maps** | Inline | External files |
|
||||
|
||||
### Desktop App (macOS & Windows)
|
||||
|
||||
The native desktop app (macOS `.app`/`.dmg`, Windows NSIS / portable `.exe`) is a self-contained deployment mode: a single Electron process embeds the Express server in-process and renders the React client in a `BrowserWindow`. No terminal, no separate `npm start`.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
LAUNCH["Open Claude Code Monitor<br/>(.app / .exe)"] --> MAIN["Electron main process<br/>(Node 22 / Electron 35)"]
|
||||
MAIN --> HOST["server-host.ts<br/>port discovery + adopt"]
|
||||
HOST --> SERVER["server/index.js (in-process)<br/>Port 4820 → fallback"]
|
||||
SERVER -->|serves| DIST["client/dist/<br/>(extraResources)"]
|
||||
MAIN --> WIN["BrowserWindow"]
|
||||
WIN --> SERVER
|
||||
|
||||
style MAIN fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style SERVER fill:#339933,stroke:#5cb85c,color:#fff
|
||||
style DIST fill:#646CFF,stroke:#818cf8,color:#fff
|
||||
```
|
||||
|
||||
The hook ingestion path (Claude Code hooks → `POST /api/hooks/event` → SQLite → WebSocket) is **identical to the standalone Production path** -- only the process that hosts the server differs. See [Desktop App Architecture](#desktop-app-architecture-macos--windows--electron) for the full design.
|
||||
|
||||
### MCP Sidecar (Optional)
|
||||
|
||||
The MCP server runs as a sidecar alongside the dashboard, connecting to the same API. It supports three transport modes:
|
||||
@@ -2792,58 +2455,6 @@ docker run -d -p 4820:4820 \
|
||||
> [!NOTE]
|
||||
> **Hook note:** Claude Code hooks run on the host, not inside the container. The containerized server still receives hook events via HTTP on `localhost:4820` — run `npm run install-hooks` on the host after the container is up. `scripts/install-hooks.js` detects container execution and refuses there (issue #193) so it cannot write a container-internal handler path into a bind-mounted host `~/.claude`; the containerized server's boot-time auto-install is skipped for the same reason. Override with `CCAM_ALLOW_CONTAINER_HOOKS=1` only when Claude Code itself runs inside the container.
|
||||
|
||||
### Cloud Deployment
|
||||
|
||||
For production cloud deployments, the `deployments/` directory provides enterprise-grade infrastructure supporting four cloud providers and multiple deployment strategies.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Deployment Pipeline"
|
||||
direction LR
|
||||
CI["CI Pipeline<br/>Build · Test · Scan"] --> DEPLOY["Deployment<br/>Helm · Kustomize · Terraform"]
|
||||
DEPLOY --> VERIFY["Verification<br/>Health Check · Smoke Tests"]
|
||||
VERIFY -->|Fail| ROLLBACK["Rollback<br/>Instant Revert"]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure"
|
||||
direction TB
|
||||
subgraph "Compute"
|
||||
BLUE["Blue Slot<br/>Current Version"]
|
||||
GREEN["Green Slot<br/>New Version"]
|
||||
end
|
||||
LB["Load Balancer<br/>TLS 1.3 · WebSocket<br/>Weighted Routing"]
|
||||
PV["Persistent Storage<br/>Encrypted NFS"]
|
||||
MON["Monitoring<br/>Prometheus · Grafana<br/>13 Alert Rules"]
|
||||
OTEL["OTel Collector<br/>Coralogix"]
|
||||
end
|
||||
|
||||
LB -->|"Active"| BLUE
|
||||
LB -.->|"Standby"| GREEN
|
||||
BLUE & GREEN --> PV
|
||||
MON -->|"Scrape"| BLUE & GREEN
|
||||
BLUE & GREEN -->|"logs + metrics + traces"| OTEL
|
||||
|
||||
style BLUE fill:#2563eb,color:#fff
|
||||
style GREEN fill:#16a34a,color:#fff
|
||||
style LB fill:#7c3aed,color:#fff
|
||||
style CI fill:#2088ff,color:#fff
|
||||
style OTEL fill:#4f46e5,color:#fff
|
||||
```
|
||||
|
||||
| Capability | Details |
|
||||
| --- | --- |
|
||||
| **Cloud Providers** | AWS (ECS Fargate + ALB), GCP (Cloud Run + GCLB), Azure (ACI + App Gateway), OCI (OKE + LBaaS) |
|
||||
| **Deployment Methods** | Helm chart, Kustomize overlays, Terraform modules |
|
||||
| **Release Strategies** | Rolling update, blue-green (instant switchover), canary (automated analysis) |
|
||||
| **Environments** | Dev, staging, production with per-environment configuration |
|
||||
| **CI/CD** | GitHub Actions and GitLab CI pipelines with Trivy security scanning |
|
||||
| **Observability** | Prometheus scraping, 13 alert rules, Grafana dashboard (16 panels), Alertmanager routing, Coralogix full-stack observability (logs, metrics, traces, SLO tracking) via OpenTelemetry Collector |
|
||||
| **Operations** | Scripts for deploy, rollback, blue-green switch, database backup/restore, teardown |
|
||||
| **Security** | Restricted PSS, network policies, TLS enforcement, OIDC auth, no long-lived credentials |
|
||||
|
||||
> [!NOTE]
|
||||
> 📘 **Full guide:** See [DEPLOYMENT.md](DEPLOYMENT.md) for step-by-step deployment instructions, and [deployments/README.md](deployments/README.md) for the infrastructure technical reference.
|
||||
|
||||
---
|
||||
|
||||
## Statusline Utility
|
||||
|
||||
Reference in New Issue
Block a user