# sparkle-project/sparkle architecture

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

- Interactive diagram: https://gitdiagram.com/sparkle-project/sparkle
- Repository: https://github.com/sparkle-project/sparkle

## Overview

##### Project type and purpose
- Sparkle 2 is a modular, secure macOS update framework that you embed into a host application.
- It exposes a Core Framework (Objective-C/Swift) plus several XPC helper services (Downloader, InstallerConnection, InstallerLauncher, InstallerStatus, Autoupdate Agent), plus command-line tools for building appcasts and deltas.

##### File structure
- Top-level “Sparkle” directory: the framework’s public/internal API and UI code.
- “Autoupdate”, “Downloader”, “InstallerConnection”, “InstallerLauncher”, “InstallerStatus”: each is a standalone XPC helper/service built as a small command-line tool or daemon for privileged operations (patch unarchiving, download with sandbox entitlements, invoking installers, reporting status).
- “BinaryDelta”, “generate_appcast”, “generate_keys”, “sign_update”, “sparkle-cli”: off-line tools for creating deltas/signatures/appcast feeds or providing a CLI interface.
- “TestApplication”/“TestAppHelper”: a sample host app + helper to exercise the framework.
- “Configurations”, “Documentation”, “Resources”, CI workflows, and tests.

##### README for additional insights
- Sparkle is embedded in the host app but uses XPC to isolate downloads, code-signing verification, and installation steps.
- Uses RSS-based appcasts served from an HTTPS server.
- Supports delta updates, signature verification (EdDSA + Apple Code Signing), sandboxing, custom UIs, phased rollouts, and multiple update drivers (automatic, user-initiated, probing).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Boundary
    subgraph "Host Application"
        direction TB
        HostApp["Host Application\n(TestApplication)"]:::host
        CoreFramework["Sparkle Core Framework"]:::host
    end

    %% XPC Helpers
    subgraph "XPC Helper Services"
        direction TB
        Downloader["SPUDownloader XPC Service"]:::helper
        InstallerConnection["InstallerConnection Service"]:::helper
        InstallerLauncher["InstallerLauncher Service"]:::helper
        InstallerStatus["InstallerStatus Service"]:::helper
        AutoupdateAgent["Autoupdate Agent"]:::helper
    end

    %% External Web Server
    WebServer["External Web Server\n(appcast & binaries)"]:::external

    %% Offline Tooling
    subgraph "Offline CLI Tools"
        direction TB
        BinaryDeltaTool["BinaryDelta Creator"]:::tool
        AppcastGenerator["Appcast Generator"]:::tool
        KeyGenerator["Key Generator"]:::tool
        UpdateSigner["Update Signer"]:::tool
        CLIInterface["Sparkle CLI"]:::tool
    end

    %% Project Files & Configurations
    subgraph "Project Files"
        direction TB
        Configurations["Configurations"]:::tool
        Documentation["Documentation"]:::tool
        Resources["Public Resources"]:::tool
        XcodeProj["Xcode Project & Schemes"]:::tool
        Tests["Tests & Test Resources"]:::tool
        UITests["UI Tests"]:::tool
        CIWorkflows["CI Workflows & Makefile"]:::tool
    end

    %% Relationships
    HostApp -->|"links SDK"| CoreFramework
    CoreFramework -->|"fetches appcast"| WebServer
    CoreFramework -->|"invokes"| Downloader
    Downloader -->|"returns data"| CoreFramework
    CoreFramework -->|"verifies signatures"| CoreFramework
    CoreFramework -->|"launches"| InstallerLauncher
    CoreFramework -->|"opens channel"| InstallerConnection
    InstallerConnection -->|"coordinates install"| CoreFramework
    InstallerLauncher -->|"spawns installer"| InstallerConnection
    InstallerStatus -->|"reports progress"| CoreFramework
    AutoupdateAgent -->|"runs background updates"| CoreFramework

    BinaryDeltaTool -->|"uploads deltas"| WebServer
    AppcastGenerator -->|"uploads feed"| WebServer
    KeyGenerator -->|"provides keys"| AppcastGenerator
    UpdateSigner -->|"signs updates"| BinaryDeltaTool
    CLIInterface -->|"manages tooling"| BinaryDeltaTool

    Configurations -->|"configure build"| XcodeProj
    Documentation -->|"guides developers"| HostApp
    Resources -->|"assets for UI"| CoreFramework
    Tests -->|"validate code"| CoreFramework
    UITests -->|"validate UI"| HostApp
    CIWorkflows -->|"automates build"| XcodeProj

    %% Click Events
    click HostApp "https://github.com/sparkle-project/sparkle/tree/2.x/TestApplication/"
    click CoreFramework "https://github.com/sparkle-project/sparkle/tree/2.x/Sparkle/"
    click Downloader "https://github.com/sparkle-project/sparkle/tree/2.x/Downloader/"
    click InstallerConnection "https://github.com/sparkle-project/sparkle/tree/2.x/InstallerConnection/"
    click InstallerLauncher "https://github.com/sparkle-project/sparkle/tree/2.x/InstallerLauncher/"
    click InstallerStatus "https://github.com/sparkle-project/sparkle/tree/2.x/InstallerStatus/"
    click AutoupdateAgent "https://github.com/sparkle-project/sparkle/tree/2.x/Autoupdate/"
    click BinaryDeltaTool "https://github.com/sparkle-project/sparkle/tree/2.x/BinaryDelta/"
    click AppcastGenerator "https://github.com/sparkle-project/sparkle/tree/2.x/generate_appcast/"
    click KeyGenerator "https://github.com/sparkle-project/sparkle/tree/2.x/generate_keys/"
    click UpdateSigner "https://github.com/sparkle-project/sparkle/tree/2.x/sign_update/"
    click CLIInterface "https://github.com/sparkle-project/sparkle/tree/2.x/sparkle-cli/"
    click Configurations "https://github.com/sparkle-project/sparkle/tree/2.x/Configurations/"
    click Documentation "https://github.com/sparkle-project/sparkle/tree/2.x/Documentation/"
    click Resources "https://github.com/sparkle-project/sparkle/tree/2.x/Resources/"
    click XcodeProj "https://github.com/sparkle-project/sparkle/tree/2.x/Sparkle.xcodeproj/"
    click Tests "https://github.com/sparkle-project/sparkle/tree/2.x/Tests/"
    click UITests "https://github.com/sparkle-project/sparkle/tree/2.x/UITests/"
    click CIWorkflows "https://github.com/sparkle-project/sparkle/tree/2.x/.github/workflows/"

    %% Styles
    classDef host fill:#e0f7ff,stroke:#333,stroke-width:1px
    classDef helper fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef tool fill:#f0f0f0,stroke:#333,stroke-width:1px
```
