# ipfs/ipfs-desktop architecture

> Architecture diagram of the GitHub repository ipfs/ipfs-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ipfs/ipfs-desktop
- Repository: https://github.com/ipfs/ipfs-desktop

## Overview

##### Main components
a. Electron Main Process
b. Electron Renderer Processes (UI)
c. IPFS Daemon (Kubo)
d. IPFS Web UI (embedded in Renderer)
e. OS Integration (Tray/Menu, Auto-launch, Protocol Handlers)
f. Local Storage & Config (Store, Log files, Kubo repo)
g. External Services (IPFS network, update server, analytics)

##### Relationships & data flows
- The Renderer (UI) communicates with the Main process via IPC (src/common/ipc-main-events.js).
- The Main process uses js-ipfsd-ctl to spawn and manage the Kubo daemon (src/daemon/\*).
- Main ↔ Daemon: control messages (start/stop/migrate/gc), and HTTP API calls for file imports, pins, peer info.
- Main creates a BrowserWindow that loads IPFS Web UI (src/webui/\* and assets downloaded via ipfs-or-gateway).
- Renderer for Files/Peers/Explore screens makes IPC calls to Main, which proxies requests to the daemon’s HTTP API or local store.
- Tray/Menu module (src/tray.js, src/app-menu.js) connects to Main to expose quick actions (import, screenshot, “Open Web UI”).
- Auto-updater module (src/auto-updater/\*) in Main checks GitHub/Snapcraft/chocolatey update endpoints and applies updates via electron-builder config.
- Analytics (src/analytics/\*) in Main batches events to remote telemetry endpoints.
- i18n loader (src/i18n.js) injects localized JSON from assets/locales into both Main and Renderer.
- Configuration store (src/common/store.js) persists user settings to disk; Kubo repo path is read from store or env var.
- On import or screenshot: Renderer triggers Main to call Kubo’s /api/v0/add, then returns CIDs back to Renderer for display and clipboard.

##### Architectural patterns & design principles
- MVC-like separation between UI (Renderer) and business logic/OS-level features (Main).
- Modular organization under src/: common utilities, dialogs, daemon, tray, webui, metrics.
- Use of Electron IPC as the API layer between UI and native functionality.
- Process isolation: Kubo runs as a separate child process; Web UI runs in a sandboxed BrowserWindow.
- Auto-update and packaging managed declaratively via electron-builder (electron-builder.yml).

##### Final checklist
- Clear component labels matching folder/module names (e.g., “Tray (src/tray.js)”).
- With relevant file paths or modules for quick reference.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Boundary
    subgraph "IPFS Desktop App"
        direction TB

        subgraph "Electron Processes"
            direction TB
            Main["Electron Main Process"]:::electron
            Renderer["Electron Renderer Processes (UI)"]:::electron
        end

        %% IPC between Main & Renderer
        Main <-->|"IPC"| Renderer

        %% Embedded Web UI in Renderer
        Renderer -->|"loads assets"| WebUI["IPFS Web UI"]:::ipfs
        WebUI -->|"HTTP API"| Daemon

        %% Main spawns Daemon
        Main -->|"spawn/control"| Daemon["IPFS Daemon (Kubo)"]:::ipfs

        %% OS Integration Modules
        subgraph "OS Integration" 
            direction TB
            Tray["Tray / Menu"]:::os
            AppMenu["App Menu"]:::os
            AutoLaunch["Auto-Launch"]:::os
            ProtocolHandlers["Protocol Handlers"]:::os
        end
        Main --> Tray
        Main --> AppMenu
        Main --> AutoLaunch
        Main --> ProtocolHandlers

        %% Main Modules
        subgraph "Main Modules"
            direction TB
            AutoUpdater["Auto-Updater"]:::os
            Analytics["Analytics / Telemetry"]:::external
            Store["Configuration Store"]:::storage
            Logger["Logging"]:::storage
            I18n["i18n Loader"]:::frontend
            FileImport["File Import Utility"]:::ipfs
            ScreenshotUtil["Screenshot Utility"]:::frontend
            Dialogs["Dialogs"]:::os
            AutoGC["Automatic GC Control"]:::ipfs
            RunGC["Run GC"]:::ipfs
            SecondInstance["Second Instance Handler"]:::os
            ArgvHandler["CLI Args Handler"]:::os
            CustomBinary["Custom IPFS Binary Selection"]:::ipfs
            Utils["Misc Utilities"]:::os
        end

        Main --> AutoUpdater
        Main --> Analytics
        Main --> Store
        Main --> Logger
        Main --> I18n
        Main --> FileImport
        Main --> ScreenshotUtil
        Main --> Dialogs
        Main --> AutoGC
        Main --> RunGC
        Main --> SecondInstance
        Main --> ArgvHandler
        Main --> CustomBinary
        Main --> Utils
    end

    %% Local Storage
    Store --> Repo["Kubo Repo (fs)"]:::storage
    Store --> ConfigFiles["Config & Logs"]:::storage

    %% External Services
    Daemon -->|"P2P"| IPFSNet["IPFS Network"]:::external
    AutoUpdater -->|"Update Check"| UpdateServer["GitHub / Snapcraft / Chocolatey"]:::external
    Analytics -->|"Telemetry Post"| Telemetry["Telemetry Endpoint"]:::external

    %% Click Events
    click Main "https://github.com/ipfs/ipfs-desktop/blob/main/src/index.js"
    click Renderer "https://github.com/ipfs/ipfs-desktop/tree/main/src/webui/"
    click Daemon "https://github.com/ipfs/ipfs-desktop/tree/main/src/daemon/"
    click WebUI "https://github.com/ipfs/ipfs-desktop/tree/main/src/webui/"
    click Ipc "https://github.com/ipfs/ipfs-desktop/blob/main/src/common/ipc-main-events.js"
    click Tray "https://github.com/ipfs/ipfs-desktop/blob/main/src/tray.js"
    click AppMenu "https://github.com/ipfs/ipfs-desktop/blob/main/src/app-menu.js"
    click AutoLaunch "https://github.com/ipfs/ipfs-desktop/blob/main/src/auto-launch.js"
    click ProtocolHandlers "https://github.com/ipfs/ipfs-desktop/blob/main/src/protocol-handlers.js"
    click AutoUpdater "https://github.com/ipfs/ipfs-desktop/blob/main/src/auto-updater/index.js"
    click ElectronBuilder "https://github.com/ipfs/ipfs-desktop/blob/main/electron-builder.yml"
    click Analytics "https://github.com/ipfs/ipfs-desktop/blob/main/src/analytics/index.js"
    click Store "https://github.com/ipfs/ipfs-desktop/blob/main/src/common/store.js"
    click Logger "https://github.com/ipfs/ipfs-desktop/blob/main/src/common/logger.js"
    click I18n "https://github.com/ipfs/ipfs-desktop/blob/main/src/i18n.js"
    click ScreenshotUtil "https://github.com/ipfs/ipfs-desktop/blob/main/src/take-screenshot.js"
    click FileImport "https://github.com/ipfs/ipfs-desktop/blob/main/src/add-to-ipfs.js"
    click Dialogs "https://github.com/ipfs/ipfs-desktop/tree/main/src/dialogs/"
    click AutoGC "https://github.com/ipfs/ipfs-desktop/blob/main/src/automatic-gc.js"
    click RunGC "https://github.com/ipfs/ipfs-desktop/blob/main/src/run-gc.js"
    click SecondInstance "https://github.com/ipfs/ipfs-desktop/blob/main/src/second-instance.js"
    click ArgvHandler "https://github.com/ipfs/ipfs-desktop/blob/main/src/argv-files-handler.js"
    click CustomBinary "https://github.com/ipfs/ipfs-desktop/blob/main/src/custom-ipfs-binary.js"
    click Utils "https://github.com/ipfs/ipfs-desktop/tree/main/src/utils/"

    %% Styles
    classDef electron fill:#cce5ff,stroke:#000,stroke-width:1px;
    classDef ipfs fill:#d4edda,stroke:#000,stroke-width:1px;
    classDef os fill:#fff3cd,stroke:#000,stroke-width:1px;
    classDef storage fill:#e2e3e5,stroke:#000,stroke-width:1px;
    classDef external fill:#ffe5b4,stroke:#000,stroke-width:1px;
    classDef frontend fill:#e0f7fa,stroke:#000,stroke-width:1px;
```
