# dhrvjgd/grabbr architecture

> Architecture diagram of the GitHub repository dhrvjgd/grabbr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhrvjgd/grabbr
- Repository: https://github.com/dhrvjgd/grabbr

## Overview

#### Purpose and Application Boundaries
Grabbr is a cross-platform desktop multimedia downloader for YouTube and Instagram. It packages a Svelte renderer inside an Electrobun/Bun desktop process, using local `yt-dlp`, FFmpeg, and ffprobe binaries; it also includes a separate public marketing web app. Core entry points are `apps/desktop/src/index.ts`, `apps/ui/src/main.ts`, and `apps/web/src/routes/+page.svelte`.

#### Desktop Host and IPC Boundary
The Electrobun main process owns native lifecycle, window integration, single-instance behavior, local persistence, process execution, and updates. `apps/desktop/src/index.ts` initializes this host; `apps/desktop/src/rpc/index.ts` exposes typed request/response handlers and one-way messages. Shared RPC shapes form the explicit renderer/main contract in `packages/contracts/src/rpc.ts`; the renderer accesses it through `apps/ui/src/lib/rpc.ts`.

#### Renderer Application
The UI is a Svelte 5 SPA providing URL submission, download controls, preferences, and status/toast presentation. `apps/ui/src/app.svelte` composes the application; `apps/ui/src/lib/components/input-url.svelte` initiates user download requests; `apps/ui/src/lib/components/options/index.svelte` organizes audio, video, encoding, sorting, update, and experimental preferences. Event listeners consume main-process download and updater messages in `apps/ui/src/lib/listeners/download.ts` and `apps/ui/src/lib/listeners/updater.ts`.

#### Download Execution Pipeline
A submitted URL and saved/current options cross RPC into the desktop download service at `apps/desktop/src/services/download.ts`. That service constructs `yt-dlp` and optional FFmpeg post-processing arguments from `apps/desktop/src/lib/args/index.ts`, including media-specific behavior in `apps/desktop/src/lib/args/audio/index.ts` and `apps/desktop/src/lib/args/video/index.ts`. Child-process spawning, output parsing, and lifecycle control are isolated in `apps/desktop/src/lib/procs.ts`; progress and terminal results are emitted back through `apps/desktop/src/callbacks/download.ts`.

#### Media Binaries and Hardware Decisions
The application ships or downloads platform-specific `yt-dlp`, FFmpeg, and ffprobe dependencies before builds via `apps/desktop/scripts/pre-build/download-binaries.ts`. Runtime binary resolution is centralized in `apps/desktop/src/lib/binary-paths.ts`. Shared media semantics and preference types live in `packages/shared/src/ytdlp.ts`, `packages/shared/src/ffmpeg.ts`, and `packages/shared/src/preferences.ts`; system GPU/vendor detection informing hardware encoding occurs in `apps/desktop/src/lib/system-info.ts`.

#### Local State and Update Services
Preferences are persisted locally in SQLite (`bun:sqlite`) behind `apps/desktop/src/services/preferences.ts`, with storage/cache concerns in `apps/desktop/src/lib/store.ts`. The UI maintains reactive preference state in `apps/ui/src/lib/preferences.svelte.ts`. `apps/desktop/src/services/update.ts` separates yt-dlp version/update operations and app auto-update integration from download work, keeping external update mechanisms outside renderer trust boundaries.

#### Packaging, Distribution, and Web Presence
`apps/desktop/electrobun.config.ts` defines desktop packaging across Windows, macOS, and Linux; pre/post build scripts prepare binaries and patch packaged artifacts. Release automation is in `.github/workflows/release.yml`. The independent SvelteKit/Vercel web app under `apps/web/src/routes/+layout.svelte` and `apps/web/src/routes/+page.svelte` serves product content rather than participating in desktop download execution.

Main entry points: [`apps/desktop/src/rpc/index.ts`](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/rpc/index.ts) (RPC handlers), [`apps/ui/src/app.svelte`](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/app.svelte) (Grabbr UI), [`apps/desktop/src/services/download.ts`](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/download.ts) (Download service), [`apps/desktop/src/lib/procs.ts`](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/procs.ts) (Process runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Desktop Renderer"]
  node_ui_entry["Renderer entry<br/>Svelte bootstrap<br/>[main.ts]"]
  node_ui_app["Grabbr UI<br/>Svelte SPA<br/>[app.svelte]"]
  node_url_input["URL submission<br/>Svelte component<br/>[input-url.svelte]"]
  node_options_ui["Download preferences<br/>Svelte component<br/>[index.svelte]"]
  node_ui_rpc["Renderer RPC client<br/>IPC client<br/>[rpc.ts]"]
  node_ui_preferences["Reactive preferences<br/>UI state"]
  node_download_listeners["Download event listener<br/>UI event handler<br/>[download.ts]"]
  node_update_listeners["Updater event listener<br/>UI event handler<br/>[updater.ts]"]
end

subgraph group_host["Desktop Host"]
  node_desktop_entry["Desktop host entry<br/>Electrobun main<br/>[index.ts]"]
  node_rpc_handlers["RPC handlers<br/>IPC server<br/>[index.ts]"]
  node_download_service["Download service<br/>desktop service<br/>[download.ts]"]
  node_preferences_service["Preferences service<br/>desktop service<br/>[preferences.ts]"]
  node_local_store[("SQLite store<br/>local persistence<br/>[store.ts]")]
  node_update_service["Update service<br/>desktop service<br/>[update.ts]"]
end

subgraph group_media["Media Execution"]
  node_argument_builder["Media argument builder<br/>download arguments<br/>[index.ts]"]
  node_process_runner["Process runner<br/>child-process control<br/>[procs.ts]"]
  node_download_callbacks["Download callbacks<br/>IPC events<br/>[download.ts]"]
  node_binary_runtime{{"Media binaries<br/>[binary-paths.ts]"}}
end

subgraph group_distribution["Distribution"]
  node_desktop_packaging["Desktop packaging<br/>Electrobun config"]
  node_release_workflow["Release automation<br/>GitHub Actions<br/>[release.yml]"]
  node_marketing_site["Marketing web app<br/>SvelteKit / Vercel<br/>[+page.svelte]"]
end

node_rpc_contract["RPC contract<br/>shared types<br/>[rpc.ts]"]
node_shared_media["Shared media semantics<br/>shared types<br/>[ytdlp.ts]"]

node_desktop_entry -->|"initializes"| node_rpc_handlers
node_ui_entry -->|"mounts"| node_ui_app
node_ui_app -->|"renders"| node_url_input
node_ui_app -->|"renders"| node_options_ui
node_url_input -->|"submits URL"| node_ui_rpc
node_options_ui -->|"edits"| node_ui_preferences
node_ui_preferences -->|"supplies options"| node_ui_rpc
node_ui_rpc -->|"implements"| node_rpc_contract
node_rpc_handlers -->|"implements"| node_rpc_contract
node_rpc_handlers -->|"dispatches download"| node_download_service
node_rpc_handlers -->|"dispatches preferences"| node_preferences_service
node_rpc_handlers -->|"dispatches updates"| node_update_service
node_preferences_service -->|"persists to"| node_local_store
node_download_service -->|"builds arguments"| node_argument_builder
node_download_service -->|"executes via"| node_process_runner
node_argument_builder -->|"uses media types"| node_shared_media
node_process_runner -->|"runs"| node_binary_runtime
node_process_runner -->|"reports lifecycle"| node_download_callbacks
node_download_callbacks -->|"sends download events"| node_download_listeners
node_update_service -->|"sends updater events"| node_update_listeners
node_desktop_packaging -->|"packages"| node_binary_runtime
node_release_workflow -->|"publishes"| node_desktop_packaging

click node_desktop_entry "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/index.ts"
click node_rpc_handlers "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/rpc/index.ts"
click node_rpc_contract "https://github.com/dhrvjgd/grabbr/blob/master/packages/contracts/src/rpc.ts"
click node_download_service "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/download.ts"
click node_preferences_service "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/preferences.ts"
click node_local_store "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/store.ts"
click node_update_service "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/update.ts"
click node_ui_entry "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/main.ts"
click node_ui_app "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/app.svelte"
click node_url_input "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/components/input-url.svelte"
click node_options_ui "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/components/options/index.svelte"
click node_ui_rpc "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/rpc.ts"
click node_ui_preferences "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/preferences.svelte.ts"
click node_download_listeners "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/listeners/download.ts"
click node_update_listeners "https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/listeners/updater.ts"
click node_argument_builder "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/args/index.ts"
click node_process_runner "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/procs.ts"
click node_download_callbacks "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/callbacks/download.ts"
click node_binary_runtime "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/binary-paths.ts"
click node_shared_media "https://github.com/dhrvjgd/grabbr/blob/master/packages/shared/src/ytdlp.ts"
click node_desktop_packaging "https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/electrobun.config.ts"
click node_release_workflow "https://github.com/dhrvjgd/grabbr/blob/master/.github/workflows/release.yml"
click node_marketing_site "https://github.com/dhrvjgd/grabbr/blob/master/apps/web/src/routes/%2Bpage.svelte"

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_ui_entry,node_ui_app,node_url_input,node_options_ui,node_ui_rpc,node_ui_preferences,node_download_listeners,node_update_listeners toneBlue
class node_desktop_entry,node_rpc_handlers,node_download_service,node_preferences_service,node_local_store,node_update_service toneAmber
class node_argument_builder,node_process_runner,node_download_callbacks,node_binary_runtime toneMint
class node_desktop_packaging,node_release_workflow,node_marketing_site toneRose
class node_rpc_contract,node_shared_media toneNeutral
```

## Components

### Desktop Renderer

Svelte SPA running in the desktop window.

- [Renderer entry](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/main.ts): Svelte bootstrap · `apps/ui/src/main.ts`
- [Grabbr UI](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/app.svelte): Svelte SPA · Composes submission, controls, preferences, and status UI. · `apps/ui/src/app.svelte`
- [URL submission](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/components/input-url.svelte): Svelte component · `apps/ui/src/lib/components/input-url.svelte`
- [Download preferences](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/components/options/index.svelte): Svelte component · `apps/ui/src/lib/components/options/index.svelte`
- [Renderer RPC client](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/rpc.ts): IPC client · `apps/ui/src/lib/rpc.ts`
- [Reactive preferences](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/preferences.svelte.ts): UI state · `apps/ui/src/lib/preferences.svelte.ts`
- [Download event listener](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/listeners/download.ts): UI event handler · `apps/ui/src/lib/listeners/download.ts`
- [Updater event listener](https://github.com/dhrvjgd/grabbr/blob/master/apps/ui/src/lib/listeners/updater.ts): UI event handler · `apps/ui/src/lib/listeners/updater.ts`

### Desktop Host

Electrobun/Bun main-process boundary.

- [Desktop host entry](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/index.ts): Electrobun main · `apps/desktop/src/index.ts`
- [RPC handlers](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/rpc/index.ts): IPC server · `apps/desktop/src/rpc/index.ts`
- [Download service](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/download.ts): desktop service · `apps/desktop/src/services/download.ts`
- [Preferences service](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/preferences.ts): desktop service · `apps/desktop/src/services/preferences.ts`
- [SQLite store](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/store.ts): local persistence · `apps/desktop/src/lib/store.ts`
- [Update service](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/services/update.ts): desktop service · Handles yt-dlp updates and app auto-update integration. · `apps/desktop/src/services/update.ts`

### Media Execution

Local binary preparation and download pipeline.

- [Media argument builder](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/args/index.ts): download arguments · Builds yt-dlp and FFmpeg arguments, including audio and video behavior. · `apps/desktop/src/lib/args/index.ts`
- [Process runner](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/procs.ts): child-process control · Spawns tools, parses output, and controls process lifecycle. · `apps/desktop/src/lib/procs.ts`
- [Download callbacks](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/callbacks/download.ts): IPC events · Emits progress and terminal download results. · `apps/desktop/src/callbacks/download.ts`
- [Media binaries](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/src/lib/binary-paths.ts): yt-dlp / FFmpeg / ffprobe · Prepared per platform and resolved at runtime. · `apps/desktop/src/lib/binary-paths.ts`

### Distribution

Desktop packaging, releases, and public site.

- [Desktop packaging](https://github.com/dhrvjgd/grabbr/blob/master/apps/desktop/electrobun.config.ts): Electrobun config · Builds Windows, macOS, and Linux artifacts. · `apps/desktop/electrobun.config.ts`
- [Release automation](https://github.com/dhrvjgd/grabbr/blob/master/.github/workflows/release.yml): GitHub Actions · `.github/workflows/release.yml`
- [Marketing web app](https://github.com/dhrvjgd/grabbr/blob/master/apps/web/src/routes/%2Bpage.svelte): SvelteKit / Vercel · Independent product-content site. · `apps/web/src/routes/+page.svelte`

### Other components

- [RPC contract](https://github.com/dhrvjgd/grabbr/blob/master/packages/contracts/src/rpc.ts): shared types · Typed renderer/main request and event boundary. · `packages/contracts/src/rpc.ts`
- [Shared media semantics](https://github.com/dhrvjgd/grabbr/blob/master/packages/shared/src/ytdlp.ts): shared types · Media and preference types shared across runtimes. · `packages/shared/src/ytdlp.ts`

## Connections

- Desktop host entry → RPC handlers: initializes
- Renderer entry → Grabbr UI: mounts
- Grabbr UI → URL submission: renders
- Grabbr UI → Download preferences: renders
- URL submission → Renderer RPC client: submits URL
- Download preferences → Reactive preferences: edits
- Reactive preferences → Renderer RPC client: supplies options
- Renderer RPC client → RPC contract: implements
- RPC handlers → RPC contract: implements
- RPC handlers → Download service: dispatches download
- RPC handlers → Preferences service: dispatches preferences
- RPC handlers → Update service: dispatches updates
- Preferences service → SQLite store: persists to
- Download service → Media argument builder: builds arguments
- Download service → Process runner: executes via
- Media argument builder → Shared media semantics: uses media types
- Process runner → Media binaries: runs
- Process runner → Download callbacks: reports lifecycle
- Download callbacks → Download event listener: sends download events
- Update service → Updater event listener: sends updater events
- Desktop packaging → Media binaries: packages
- Release automation → Desktop packaging: publishes
