Architecture

Architecture

Zegplayer is an Electron app built with electron-vite and TypeScript. It is split into four runtime pieces plus a local store.

┌─────────────┐   IPC    ┌─────────────┐         ┌──────────────────────┐
│  Renderer   │ ───────▶ │   Preload   │ ──────▶ │     Main process     │
│ (vanilla TS │ ◀─────── │ contextBridge│ ◀────── │ lifecycle + tooling  │
│  templates) │          └─────────────┘         └──────────┬───────────┘
└─────────────┘                                             │ spawns
                                                            ▼
                              ffmpeg / whisper-cli / yt-dlp / AI CLIs / model servers
                                                            │
                              ┌──────────────┐              ▼
                              │ SQLite store │◀──── better-sqlite3 (agentic-video.sqlite)
                              └──────┬───────┘
                                     │ read-only
                              ┌──────▼───────┐
                              │  MCP server  │  ◀── agents query transcripts/notes
                              └──────────────┘

Processes

• Main (src/main/) — app lifecycle, windowing, and orchestration of external tools. Owns the SQLite store, job queue, provider detection, install helpers, transcription, export, and YouTube import. Exposes everything to the renderer through ipcMain.handle.
• Preload (src/preload/) — the secure contextBridge that exposes a constrained, typed DesktopApi (see src/shared/types.ts) to the renderer. No Node access leaks into the page.
• Renderer (src/renderer/) — the UI. Vanilla TypeScript with template-literal HTML (no framework). Library, player, services dialog, shortcuts, etc.
• MCP server (src/mcp/server.ts) — a separate process exposing a read-only Model Context Protocol server (built on @modelcontextprotocol/sdk, zod for schemas) so AI agents can query your data. Bundled with tsup into dist-mcp/.

Data

• SQLite via better-sqlite3, file agentic-video.sqlite inside the app's userData directory. (The filename keeps its original name across the rebrand so existing data is never orphaned.)
• On a packaged build the userData dir is …/Zegplayer/. The app migrates a legacy …/Agentic Video Player/ directory on first launch if present.

Key conventions

• Every source file stays under 300 lines; split into focused modules past that.
• Native modules (better-sqlite3, bindings, file-uri-to-path) and the bundled MCP server are asarUnpack-ed so they load from a packaged build.
• Main/preload changes require a full npm run dev restart (HMR only covers the renderer).

Build & release

electron-builder produces per-OS installers. Native modules can't be cross-compiled, so each platform's installer is built on that platform (CI matrix). Pushing a vX.Y.Z tag drafts a GitHub Release with the installers attached.