How tres-joli/grabbr works
Grabbr is a three-tier Electron desktop app with a clear split between UI, bridge, and privileged backend logic.
At a high level, the architecture is:
• Electron main process: owns the desktop window, filesystem access, subprocess execution, preferences storage, and update/download orchestration.
• Preload layer: exposes a narrow, safe API from main to renderer.
• React renderer: presents the downloader UI and settings screens, and calls into the main process only through the preload bridge.
Main subsystems
1) Renderer UI layer
Location: src/renderer
This is the user-facing React 19 application. It contains:
• The main app shell in App.tsx
• Input and option controls for download setup
• Tabbed configuration panels for:
- General
- Audio
- Video
- Encoding
- Sorting
- Updates
- Experimental
• Reusable UI primitives in src/renderer/src/components/ui
• A preferences provider in src/renderer/src/components/providers/preferences.tsx
• A generic IPC hook in src/renderer/src/components/use-ipc.tsx
This layer is responsible for:
• collecting the URL to download
• letting the user choose audio/video mode and output settings
• showing progress, status, and errors
• triggering folder/file pickers through IPC
• reflecting saved preferences from the main process
It does not directly touch the filesystem or spawn processes.
2) Preload bridge
Location: src/preload
The preload layer is the security boundary between the renderer and Electron’s privileged APIs. It exposes a controlled API surface to the React app through contextBridge.
Architecturally, this means:
• the renderer cannot call Node/Electron APIs directly
• all privileged operations go through a typed bridge
• the app can keep renderer code mostly framework/UI-focused
3) Electron main process
Location: src/main
This is the application backend and contains the core workflow logic.
Main entry and app lifecycle
• src/main/index.ts is the main process entry point
• It likely creates the BrowserWindow, initializes IPC handlers, loads preferences, and wires services together
IPC handlers
Location: src/main/ipc
This folder is the request/response boundary between renderer and main. It includes handlers for:
• download.ts — start/cancel/download-related actions
• preferences.ts — read/write user preferences
• dialog.ts — native folder/file chooser dialogs
• updater.ts — app and yt-dlp update actions
• ytdlp.ts — yt-dlp version/query/update operations
These handlers are the coordination layer. They do not implement the actual download mechanics themselves; instead they delegate to controllers and services.
Controllers
Location: src/main/controller
Controllers encapsulate high-level use cases:
• download.ts — orchestrates the download flow
• preferences.ts — manages reading, normalizing, and saving user settings
Controllers sit above the lower-level services and translate UI-driven intent into actual work.
Services
Location: src/main/services
This is where the lower-level operational logic lives.
Key services include:
• procs.ts — process spawning, child process management, cancellation
• binary-paths.ts — resolves packaged/local paths to bundled executables
• system-info.ts — platform/runtime info used for behavior or display
• ytdlp/download.ts — download execution built around yt-dlp
• ytdlp/update.ts — checks and updates the installed yt-dlp
• ytdlp/args/* — builds command-line arguments for yt-dlp by concern:
- audio
- video
- sorting
- post-process
- argument composition/index
This service layer is the bridge to external executables and the operating system.
Persistent store
• src/main/store.ts uses electron-store for persistent app state
This stores user preferences such as:
• theme
• download folder behavior
• audio/video settings
• experimental cookie file setting
• update-related state
4) Shared code
Location: src/shared
Shared constants and utilities are used by both main and renderer to keep data shapes and common logic aligned.
This is important architecturally because it reduces drift between the UI and backend IPC contracts.
Core data flow: download lifecycle
The most important system flow is the media download path.
1. The user enters a URL in the renderer.
2. The user selects download mode and options:
- audio or video
- preset or custom settings
- output format/quality/container
- metadata/chapter embedding
- sorting or encoding preferences
3. The renderer sends a download request through the preload bridge and IPC.
4. The main process download controller receives the request.
5. The controller composes yt-dlp command arguments using the ytdlp/args modules.
6. The service layer resolves binary paths for:
- yt-dlp
- ffmpeg
- ffprobe
7. procs.ts launches the subprocess and tracks it.
8. Progress, completion, cancellation, and errors are reported back to the renderer through IPC.
9. If needed, native dialogs are used for choosing a folder or file.
10. Preferences are saved to electron-store so the next session can reuse them.
This means the actual media work happens outside Electron in bundled command-line tools, while Electron coordinates the UX and state.
External executables and binary boundary
A major architectural feature of this repo is that Grabbr is not implementing media downloading itself. It shells out to external tools.
Bundled binaries:
• yt-dlp
• ffmpeg
• ffprobe
The README indicates these are downloaded into resources/bin/ by scripts/download-binaries.ts. That makes the app self-contained at runtime and avoids depending on system-installed tools.
This introduces a key boundary:
• the Electron app owns orchestration
• the binaries own extraction, muxing, and media processing
Preferences and state flow
Preferences are persistent and shared across sessions.
Flow:
• Renderer displays current settings through a preferences provider
• User changes settings in the UI
• Renderer sends preference updates through IPC
• Main process writes them to electron-store
• On startup, main reloads the stored values and exposes them back to the renderer
This gives the app a desktop-native workflow where options persist without requiring a backend service or remote account.
Update architecture
Grabbr has two different update concerns:
1) App auto-update
• Handled in src/main/updater.ts and IPC updater handlers
• Uses electron-updater
• Designed for packaged production builds
• Release pipeline is driven by GitHub Actions
2) yt-dlp version update
• Separate from app updates
• Handled in the ytdlp/update.ts service and related IPC/controller paths
• Lets the user update the bundled downloader directly from inside the app
This separation matters: the desktop shell can update independently of the embedded media tool.
Experimental cookies support
The experimental feature for cookies.txt is another notable subsystem.
Architecture-wise:
• the renderer lets the user choose a cookies file
• the path is persisted in preferences
• the main process injects it into yt-dlp execution when enabled
• the app cleans up after use as needed
This is an optional request-time augmentation of the download command, not a separate storage system.
Packaging and build pipeline
Relevant tooling:
• Electron 41
• React 19
• TypeScript 5
• electron-vite for development/build integration
• electron-builder for packaging
• Bun for package management and scripts
Build artifacts and platform config:
• electron-builder.yml
• electron.vite.config.ts
• build/ assets for icons and macOS entitlements
• GitHub Actions workflow in .github/workflows/release.yml
The release pipeline builds desktop installers/binaries for Windows, macOS, and Linux from version tags. That means the repository is structured around desktop distribution rather than a server deployment model.
Architectural boundaries to capture in a diagram
If you are drawing the architecture, the main boundaries are:
• User interface boundary: React renderer
• Secure bridge boundary: preload
• Privileged desktop boundary: Electron main process
• Command execution boundary: subprocesses for yt-dlp/ffmpeg/ffprobe
• Persistence boundary: electron-store on local disk
• Update boundary: app update channel vs yt-dlp update channel
• Packaging boundary: bundled binaries and desktop installers
Summary
Grabbr is a local-first Electron downloader. The renderer is responsible for UX and settings, the preload layer constrains access, and the main process orchestrates downloads, preferences, dialogs, and updates. Actual media processing is delegated to bundled external binaries, with persistent configuration managed locally through electron-store. The result is a desktop app architecture optimized for offline, fast, stateful multimedia downloads rather than a networked client/server system.
Main entry points: controller/download.ts Download ctrl · index.ts Main entry · ytdlp/download.ts Download svc · use-ipc.tsx IPC hook
Components 27
Renderer
React UI and state presentation
- App shell · Top-level renderer entry and app composition
src/renderer/src/App.tsx - URL input · Download URL entry and primary controls
src/renderer/src/components/input-url.tsx - Options tabs · General, audio, video, encoding, sorting, updates, and experimental panels
src/renderer/src/components/options/index.tsx - Prefs provider · Renderer-side preferences state and sync
src/renderer/src/components/providers/preferences.tsx - IPC hook · Generic renderer API for invoking preload-exposed channels
src/renderer/src/components/use-ipc.tsx
Preload
Secure IPC bridge
- Bridge API · Typed, narrowed API exposed to the renderer
src/preload/index.ts
Main Process
Privileged desktop orchestration
- Main entry · Process bootstrap and wiring for the desktop app
src/main/index.ts - IPC router · Registers request/response handlers
src/main/ipc/index.ts - Download IPC · Start, cancel, and progress-related download actions
src/main/ipc/download.ts - Prefs IPC · Read and write preference state
src/main/ipc/preferences.ts - Dialog IPC · Native file and folder chooser actions
src/main/ipc/dialog.ts - Updater IPC · App and yt-dlp update actions
src/main/ipc/updater.ts - yt-dlp IPC · yt-dlp version and update operations
src/main/ipc/ytdlp.ts - Download ctrl · Orchestrates the end-to-end download flow
src/main/controller/download.ts - Prefs ctrl · Normalizes, loads, and saves preferences
src/main/controller/preferences.ts - Local store · Persistent desktop state on disk
src/main/store.ts - App updater · Packaged application update channel
src/main/updater.ts
Services
OS, process, and yt-dlp integration
- Download svc · Runs media downloads through external tools
src/main/services/ytdlp/download.ts - Arg builders · Composes audio, video, sorting, and post-process arguments
src/main/services/ytdlp/args/index.ts - Process svc · Spawns, tracks, and cancels child processes
src/main/services/procs.ts - Binary paths · Resolves bundled executable locations
src/main/services/binary-paths.ts - yt-dlp update · Checks and updates the bundled yt-dlp binary
src/main/services/ytdlp/update.ts - System info · Platform and environment details used by backend logic
src/main/services/system-info.ts
Shared
Constants and cross-process helpers
- Shared consts · Cross-process constants and common values
src/shared/constants.ts - Shared utils · Common helpers used by both renderer and main
src/shared/utils.ts
Packaging
Build, binaries, and release tooling
- Bundled binaries · yt-dlp, ffmpeg, and ffprobe shipped with the app
scripts/download-binaries.ts - Release build · Desktop packaging and release workflow
.github/workflows/release.yml
Connections 30
- App shell → URL input: renders · App shell composes the download input surface
- App shell → Options tabs: renders · App shell hosts the settings panels
- App shell → Prefs provider: uses · App consumes shared preferences state
- URL input → IPC hook: requests · Triggers download and picker actions through bridge APIs
- Options tabs → IPC hook: saves · Sends settings changes through IPC
- Prefs provider → IPC hook: syncs · Loads and updates persisted preferences via bridge
- IPC hook → Bridge API: calls · Renderer talks only to the exposed preload API
- Bridge API → IPC router: exposes · Bridge routes safe requests into main IPC
- Main entry → IPC router: registers · Bootstraps the IPC handler set
- Main entry → Download ctrl: wires · Main process connects app events to download orchestration
- Main entry → Prefs ctrl: wires · Main process connects startup and settings handling
- Download IPC → Download ctrl: delegates · Download IPC forwards use-case requests
- Prefs IPC → Prefs ctrl: delegates · Preferences IPC forwards read/write requests
- Dialog IPC → Main entry: uses · Dialogs are part of the privileged desktop boundary
- Updater IPC → App updater: delegates · App update actions are handled by updater logic
- Updater IPC → yt-dlp update: delegates · yt-dlp update actions are handled separately from app updates
- yt-dlp IPC → yt-dlp update: delegates · Version and update queries reach yt-dlp service logic
- Download ctrl → Arg builders: builds · Composes tool arguments from UI preferences and mode selection
- Download ctrl → Download svc: starts · Hands off execution once the request is normalized
- Download ctrl → Local store: reads/writes · Uses saved settings during download orchestration
- Prefs ctrl → Local store: persists · Preference changes are saved locally
- Download svc → Binary paths: resolves · Finds bundled yt-dlp, ffmpeg, and ffprobe paths
- Download svc → Process svc: spawns · Launches and tracks the subprocess execution
- Download svc → Shared consts: uses · Shares common types and values with the rest of the app
- Arg builders → Shared utils: uses · Reuses helpers while composing command arguments
- yt-dlp update → Binary paths: resolves · Locates the bundled downloader binary for update checks
- System info → Main entry: informs · Runtime/platform info can influence backend behavior
- Bundled binaries → Binary paths: provides · Packaged executables are the target of path resolution
- Release build → Bundled binaries: packages · Release workflow bundles desktop binaries and installers
- Release build → App updater: publishes · Release pipeline feeds the app auto-update channel