docs: add documentation for desktop auto-updater, configuration, IPC architecture, and project overview

2026-04-05 23:03:40 +07:00
parent a13feb1c51
commit 8cac18edf4
4 changed files with 910 additions and 0 deletions
@@ -0,0 +1,127 @@
+# Eigen Desktop
+
+An Electron wrapper for the web applications in this monorepo. Powered by **electron-vite** for development and **electron-builder** for production packaging.
+
+---
+
+## Quick Start
+
+```bash
+# From the monorepo root
+
+# Install dependencies
+pnpm install
+
+# Development (starts both the web dev server and Electron)
+pnpm dev:desktop
+
+# Build for production
+pnpm build:desktop
+
+# Package for distribution
+pnpm package:desktop
+```
+
+---
+
+## How It Works
+
+| Environment | Behavior |
+|---|---|
+| **Development** | Electron loads the Vite dev server (`http://localhost:5173`). Hot reload works normally. |
+| **Production** | Electron registers a custom `app://` protocol that serves the static build output of the target web app. SPA client-side routing is fully supported via an `index.html` fallback. |
+
+---
+
+## Project Structure
+
+```
+apps/desktop/
+├── docs/                    # Documentation
+│   ├── CONFIGURATION.md     # Target app, routing, HashRouter fallback
+│   ├── AUTO_UPDATER.md      # Release process, CI/CD, code signing
+│   └── IPC_ARCHITECTURE.md  # Security model, adding new features
+├── scripts/
+│   └── copy-web-dist.ts     # Prebuild: copies web app build → web-dist/
+├── src/
+│   ├── main/
+│   │   └── index.ts         # Main process: protocol, CORS, IPC, updater
+│   ├── preload/
+│   │   └── index.ts         # Secure contextBridge API
+│   └── renderer/
+│       └── index.html       # Renderer shell (CSP reference)
+├── .env                     # Target app configuration
+├── electron-builder.yml     # Packaging & auto-update config
+├── electron-vite.config.ts  # Build config (main, preload, renderer)
+├── package.json
+├── tsconfig.json
+├── tsconfig.main.json
+├── tsconfig.preload.json
+└── tsconfig.renderer.json
+```
+
+---
+
+## Scripts
+
+| Script | Description |
+|---|---|
+| `pnpm dev` | Start electron-vite dev server |
+| `pnpm build` | Compile TypeScript → `out/` |
+| `pnpm prebuild` | Copy target web app's `dist/` → `web-dist/` |
+| `pnpm package` | Build + package for current platform |
+| `pnpm package:win` | Package for Windows (NSIS) |
+| `pnpm package:mac` | Package for macOS (DMG + ZIP) |
+| `pnpm package:linux` | Package for Linux (AppImage) |
+
+---
+
+## Configuration
+
+The target web app is configured via `.env`:
+
+```env
+DESKTOP_TARGET_APP=web
+DESKTOP_DEV_SERVER_URL=http://localhost:5173
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for details on switching target apps and routing fallbacks.
+
+---
+
+## Features
+
+### Custom `app://` Protocol
+Serves the web app's static build with SPA routing support. Includes path traversal protection and CSP header injection.
+
+### Hardware Printing
+The React app can list printers and trigger print jobs via `window.electronAPI.getPrinters()` and `window.electronAPI.print()`.
+
+### Auto-Update
+Background update checks via GitHub Releases with download progress forwarding to the React UI. See [docs/AUTO_UPDATER.md](docs/AUTO_UPDATER.md).
+
+### CORS Bypass
+API requests from the `app://` origin are transparently handled by stripping non-standard Origin headers and injecting CORS response headers.
+
+---
+
+## Security
+
+- `contextIsolation: true` — preload runs in an isolated context
+- `nodeIntegration: false` — no Node.js APIs in the renderer
+- `sandbox: true` — Chromium sandbox enabled
+- `webSecurity: true` — same-origin policy enforced
+- Path traversal protection in the custom protocol handler
+- CSP headers injected on all HTML responses
+
+See [docs/IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) for the full security model and how to safely extend the app.
+
+---
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [CONFIGURATION.md](docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
+| [AUTO_UPDATER.md](docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, S3/generic provider switching, code signing |
+| [IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extension guide |