# vslavik/winsparkle architecture

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

- Interactive diagram: https://gitdiagram.com/vslavik/winsparkle
- Repository: https://github.com/vslavik/winsparkle

## Overview

1. **What this repo is**
   WinSparkle is a Windows auto-update library, not an application. The core deliverable is a `WinSparkle.dll` that hosts embed into their own desktop apps. The repo also includes a small command-line signing tool, example host apps, language bindings, and packaging/build files.

2. **Public integration boundary**
   The main external API is the C header in `include/winsparkle.h`, plus version metadata in `include/winsparkle-version.h`. Host applications link against the DLL and configure it with their update feed URL, app identity, and cryptographic public key. The readme highlights two key integration modes for the public key: a Windows resource or a runtime API call.

3. **Update lifecycle and control flow**
   The runtime path is centered in `src/appcontroller.cpp`. It coordinates the update check flow: read settings, fetch the appcast, decide whether a newer release exists, verify it, and then hand off to download/UI. This is the architectural “spine” of the library.

4. **Feed retrieval and release discovery**
   `src/updatechecker.cpp`, `src/download.cpp`, and `src/appcast.cpp` handle the network-facing part of the system. The appcast is the update manifest format, compatible with Sparkle, and contains the release metadata plus a signed download enclosure. The data flow is: update URL → appcast fetch → XML parse → candidate release selection.

5. **Manifest parsing**
   `src/appcast.*` is the boundary between the raw XML feed and internal update records. It extracts release fields, enclosure information, and signature attributes from the appcast format. Expat appears in `3rdparty/expat`, indicating XML parsing is a deliberate external dependency rather than ad hoc string processing.

6. **Security and signature verification**
   `src/signatureverifier.cpp` is the security gate before any installer is trusted. The readme says WinSparkle supports modern EdDSA/Ed25519 signatures and legacy DSA signatures for compatibility. Crypto dependencies are bundled under `3rdparty/ed25519`, `3rdparty/openssl`, and related build files, showing that verification is a first-class subsystem rather than a helper.

7. **Download and install handoff**
   `src/updatedownloader.cpp` and `src/download.cpp` are responsible for fetching the update payload after a release is accepted. The library does not itself perform the application upgrade logic; instead it downloads the installer and then delegates user-facing install/launch behavior to the host/runtime contract.

8. **User interaction layer**
   `src/ui.cpp` is the visible update experience: prompts, progress, and decision dialogs. The repo includes `3rdparty/wxWidgets`, and the translations directory strongly suggests the UI is built on wxWidgets and localized through gettext-style `.po` files. This is a separate presentation boundary from the update-checking logic.

9. **Settings, persistence, and runtime state**
   `src/settings.cpp` stores library configuration and user/update-check state. This is where the library remembers things like update frequency, deferred choices, or other preferences across launches. It acts as the persistence boundary between the host app and the update engine.

10. **DLL and Windows-specific entry points**
   `src/dll_api.cpp` and `src/dllmain.cpp` are the Windows DLL-facing layers, wiring exported functions and process attach/detach behavior. The `src/winsparkle.rc` resource file and `translations/translations.rc` suggest Windows resource embedding is used for versioning, branding, and localization.

11. **Threading and concurrency**
   `src/threads.cpp` indicates background work is separated from the host UI thread. That matters architecturally because update checks and downloads are asynchronous operations that should not block the application’s main message loop.

12. **Tooling and signing companion**
   `tools/winsparkle-tool.cpp` builds a separate CLI used to generate EdDSA keys and sign update binaries. This is a distinct utility boundary: the application runtime consumes signed update metadata, while the tool produces the signatures offline. The `bin/legacy_*.bat` scripts preserve older DSA workflows.

13. **Example hosts and bindings**
   `examples/psdk` and `examples/qt` show how different host-app UI stacks integrate the library. `pascal/` contains Delphi/Lazarus bindings, and the README references .NET, Python, and Go bindings maintained externally. These are integration surfaces, not part of the core update engine.

14. **Build, packaging, and distribution**
   The project supports Visual Studio solution/project files at the root, NuGet packaging in `nuget/`, and an “unsupported” CMake path under `cmake/`. CI is handled by GitHub Actions (`.github/workflows/build.yml` and translation checks). Third-party dependencies are vendored under `3rdparty/` and wired into the build, which makes the repo self-contained for Windows builds.

15. **External dependencies and services**
   The update payload comes from an appcast hosted elsewhere on the internet, and translations are synced through Crowdin (`crowdin.yml`). The library itself depends materially on wxWidgets for UI, Expat for XML, and OpenSSL/Ed25519 for crypto, but the app’s actual installer/update distribution remains external to this repo.

Main entry points: [`src/appcontroller.cpp`](https://github.com/vslavik/winsparkle/blob/master/src/appcontroller.cpp) (Controller), [`include/winsparkle.h`](https://github.com/vslavik/winsparkle/blob/master/include/winsparkle.h) (Public API), [`cmake/CMakeLists.txt`](https://github.com/vslavik/winsparkle/blob/master/cmake/CMakeLists.txt) (CMake build), [`src/appcast.cpp`](https://github.com/vslavik/winsparkle/blob/master/src/appcast.cpp) (Appcast parse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core runtime"]
  node_n_settings[("Settings<br/>state store<br/>[settings.cpp]")]
  node_n_appcontroller["Controller<br/>update spine<br/>[appcontroller.cpp]"]
  node_n_updatechecker["Check updates<br/>network flow<br/>[updatechecker.cpp]"]
  node_n_appcast["Appcast parse<br/>feed parser<br/>[appcast.cpp]"]
  node_n_signatureverifier{{"Verify sig<br/>crypto gate"}}
  node_n_download["Download<br/>fetcher<br/>[download.cpp]"]
  node_n_updatedownloader["Installer handoff"]
  node_n_ui["Update UI<br/>presentation<br/>[ui.cpp]"]
  node_n_threads(("Background work<br/>concurrency<br/>[threads.cpp]"))
end

subgraph group_grp_public["Public surface"]
  node_n_include_api["Public API<br/>C header<br/>[winsparkle.h]"]
  node_n_include_version["Version info<br/>version header"]
  node_n_dll_api["DLL exports<br/>entrypoints<br/>[dll_api.cpp]"]
  node_n_dllmain["DLL init<br/>dll lifecycle<br/>[dllmain.cpp]"]
end

subgraph group_grp_tooling["Tooling"]
  node_n_tool["Signing tool<br/>CLI utility"]
end

subgraph group_grp_examples["Examples and bindings"]
  node_n_example_psdk["PSDK example<br/>sample host<br/>[app_psdk.c]"]
  node_n_example_qt["Qt example<br/>sample host<br/>[main.cpp]"]
  node_n_pascal["Pascal bindings<br/>language binding<br/>[winsparkle.pas]"]
end

subgraph group_grp_deps["Bundled deps"]
  node_n_wxwidgets["wxWidgets<br/>ui library"]
  node_n_expat["Expat<br/>xml parser"]
  node_n_openssl["OpenSSL<br/>crypto lib"]
  node_n_ed25519["Ed25519<br/>crypto lib"]
end

subgraph group_grp_build["Build and release"]
  node_n_sln["VS solution<br/>build root<br/>[WinSparkle.sln]"]
  node_n_cmake["CMake build<br/>build config<br/>[CMakeLists.txt]"]
  node_n_nuget["NuGet package<br/>distribution<br/>[WinSparkle.nuspec]"]
  node_n_translations["Translations<br/>localization<br/>[translations.rc]"]
end

node_n_include_api -->|"declares"| node_n_dll_api
node_n_include_version -.->|"versions"| node_n_nuget
node_n_dllmain -->|"starts"| node_n_appcontroller
node_n_dll_api -->|"configures"| node_n_settings
node_n_dll_api -->|"drives"| node_n_appcontroller
node_n_appcontroller -->|"reads/writes"| node_n_settings
node_n_appcontroller -->|"checks"| node_n_updatechecker
node_n_updatechecker -->|"fetches/parses"| node_n_appcast
node_n_appcast -.->|"parses with"| node_n_expat
node_n_appcast -->|"provides signature"| node_n_signatureverifier
node_n_signatureverifier -->|"verifies with"| node_n_ed25519
node_n_signatureverifier -->|"verifies with"| node_n_openssl
node_n_appcontroller -->|"prompts"| node_n_ui
node_n_ui -.->|"built on"| node_n_wxwidgets
node_n_appcontroller -->|"runs on"| node_n_threads
node_n_threads -->|"executes"| node_n_download
node_n_appcontroller -->|"handoffs to"| node_n_updatedownloader
node_n_updatedownloader -->|"uses"| node_n_download
node_n_tool -->|"produces signatures"| node_n_ed25519
node_n_tool -.->|"legacy support"| node_n_openssl
node_n_example_psdk -->|"integrates via"| node_n_include_api
node_n_example_qt -->|"integrates via"| node_n_include_api
node_n_pascal -->|"binds to"| node_n_include_api
node_n_sln -->|"builds"| node_n_include_api
node_n_cmake -.->|"configures"| node_n_wxwidgets
node_n_cmake -.->|"configures"| node_n_expat
node_n_cmake -.->|"configures"| node_n_openssl
node_n_nuget -->|"packages"| node_n_include_api
node_n_translations -->|"localizes"| node_n_ui

click node_n_include_api "https://github.com/vslavik/winsparkle/blob/master/include/winsparkle.h"
click node_n_include_version "https://github.com/vslavik/winsparkle/blob/master/include/winsparkle-version.h"
click node_n_dll_api "https://github.com/vslavik/winsparkle/blob/master/src/dll_api.cpp"
click node_n_dllmain "https://github.com/vslavik/winsparkle/blob/master/src/dllmain.cpp"
click node_n_settings "https://github.com/vslavik/winsparkle/blob/master/src/settings.cpp"
click node_n_appcontroller "https://github.com/vslavik/winsparkle/blob/master/src/appcontroller.cpp"
click node_n_updatechecker "https://github.com/vslavik/winsparkle/blob/master/src/updatechecker.cpp"
click node_n_appcast "https://github.com/vslavik/winsparkle/blob/master/src/appcast.cpp"
click node_n_signatureverifier "https://github.com/vslavik/winsparkle/blob/master/src/signatureverifier.cpp"
click node_n_download "https://github.com/vslavik/winsparkle/blob/master/src/download.cpp"
click node_n_updatedownloader "https://github.com/vslavik/winsparkle/blob/master/src/updatedownloader.cpp"
click node_n_ui "https://github.com/vslavik/winsparkle/blob/master/src/ui.cpp"
click node_n_threads "https://github.com/vslavik/winsparkle/blob/master/src/threads.cpp"
click node_n_tool "https://github.com/vslavik/winsparkle/blob/master/tools/winsparkle-tool.cpp"
click node_n_example_psdk "https://github.com/vslavik/winsparkle/blob/master/examples/psdk/app_psdk.c"
click node_n_example_qt "https://github.com/vslavik/winsparkle/blob/master/examples/qt/main.cpp"
click node_n_pascal "https://github.com/vslavik/winsparkle/blob/master/pascal/winsparkle.pas"
click node_n_wxwidgets "https://github.com/vslavik/winsparkle/tree/master/3rdparty/wxWidgets"
click node_n_expat "https://github.com/vslavik/winsparkle/tree/master/3rdparty/expat"
click node_n_openssl "https://github.com/vslavik/winsparkle/tree/master/3rdparty/openssl"
click node_n_ed25519 "https://github.com/vslavik/winsparkle/tree/master/3rdparty/ed25519"
click node_n_sln "https://github.com/vslavik/winsparkle/blob/master/WinSparkle.sln"
click node_n_cmake "https://github.com/vslavik/winsparkle/blob/master/cmake/CMakeLists.txt"
click node_n_nuget "https://github.com/vslavik/winsparkle/blob/master/nuget/WinSparkle.nuspec"
click node_n_translations "https://github.com/vslavik/winsparkle/blob/master/translations/translations.rc"

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_n_settings,node_n_appcontroller,node_n_updatechecker,node_n_appcast,node_n_signatureverifier,node_n_download,node_n_updatedownloader,node_n_ui,node_n_threads toneBlue
class node_n_include_api,node_n_include_version,node_n_dll_api,node_n_dllmain toneAmber
class node_n_tool toneMint
class node_n_example_psdk,node_n_example_qt,node_n_pascal toneRose
class node_n_wxwidgets,node_n_expat,node_n_openssl,node_n_ed25519 toneIndigo
class node_n_sln,node_n_cmake,node_n_nuget,node_n_translations toneTeal
```

## Components

### Core runtime

Library runtime that checks for updates, verifies releases, downloads installers, and coordinates UI.

- [Settings](https://github.com/vslavik/winsparkle/blob/master/src/settings.cpp): state store · Persistent configuration and update-check state. · `src/settings.cpp`
- [Controller](https://github.com/vslavik/winsparkle/blob/master/src/appcontroller.cpp): update spine · Coordinates the end-to-end update lifecycle. · `src/appcontroller.cpp`
- [Check updates](https://github.com/vslavik/winsparkle/blob/master/src/updatechecker.cpp): network flow · Starts update checks and orchestrates appcast retrieval. · `src/updatechecker.cpp`
- [Appcast parse](https://github.com/vslavik/winsparkle/blob/master/src/appcast.cpp): feed parser · Parses update manifest XML into release records. · `src/appcast.cpp`
- [Verify sig](https://github.com/vslavik/winsparkle/blob/master/src/signatureverifier.cpp): crypto gate · Validates release signatures before trust or install. · `src/signatureverifier.cpp`
- [Download](https://github.com/vslavik/winsparkle/blob/master/src/download.cpp): fetcher · Retrieves update payloads from the release enclosure. · `src/download.cpp`
- [Installer handoff](https://github.com/vslavik/winsparkle/blob/master/src/updatedownloader.cpp): handoff · Manages post-acceptance download and install transition. · `src/updatedownloader.cpp`
- [Update UI](https://github.com/vslavik/winsparkle/blob/master/src/ui.cpp): presentation · Dialogs, prompts, and progress UI shown to the user. · `src/ui.cpp`
- [Background work](https://github.com/vslavik/winsparkle/blob/master/src/threads.cpp): concurrency · Runs update activity off the host UI thread. · `src/threads.cpp`

### Public surface

Headers, DLL entry points, and host integration points exposed to applications.

- [Public API](https://github.com/vslavik/winsparkle/blob/master/include/winsparkle.h): C header · Main host-facing API for configuring and driving WinSparkle. · `include/winsparkle.h`
- [Version info](https://github.com/vslavik/winsparkle/blob/master/include/winsparkle-version.h): version header · Compile-time version metadata exposed to hosts and packaging. · `include/winsparkle-version.h`
- [DLL exports](https://github.com/vslavik/winsparkle/blob/master/src/dll_api.cpp): entrypoints · Exported functions that form the Windows DLL boundary. · `src/dll_api.cpp`
- [DLL init](https://github.com/vslavik/winsparkle/blob/master/src/dllmain.cpp): dll lifecycle · Process attach/detach and library initialization hooks. · `src/dllmain.cpp`

### Tooling

Offline signing and packaging utilities.

- [Signing tool](https://github.com/vslavik/winsparkle/blob/master/tools/winsparkle-tool.cpp): CLI utility · Generates keys and signs update binaries offline. · `tools/winsparkle-tool.cpp`

### Examples and bindings

Sample hosts and language bindings showing integration patterns.

- [PSDK example](https://github.com/vslavik/winsparkle/blob/master/examples/psdk/app_psdk.c): sample host · Native Windows example showing host integration. · `examples/psdk/app_psdk.c`
- [Qt example](https://github.com/vslavik/winsparkle/blob/master/examples/qt/main.cpp): sample host · Qt-based example demonstrating GUI integration. · `examples/qt/main.cpp`
- [Pascal bindings](https://github.com/vslavik/winsparkle/blob/master/pascal/winsparkle.pas): language binding · Delphi/Lazarus bindings for integrating the library. · `pascal/winsparkle.pas`

### Bundled deps

Vendored third-party libraries used by the core runtime and tooling.

- [wxWidgets](https://github.com/vslavik/winsparkle/tree/master/3rdparty/wxWidgets): ui library · Third-party GUI toolkit used by the user interaction layer. · `3rdparty/wxWidgets`
- [Expat](https://github.com/vslavik/winsparkle/tree/master/3rdparty/expat): xml parser · XML parsing dependency used for appcast handling. · `3rdparty/expat`
- [OpenSSL](https://github.com/vslavik/winsparkle/tree/master/3rdparty/openssl): crypto lib · Bundled crypto dependency supporting legacy verification paths. · `3rdparty/openssl`
- [Ed25519](https://github.com/vslavik/winsparkle/tree/master/3rdparty/ed25519): crypto lib · Bundled modern signature implementation for update verification. · `3rdparty/ed25519`

### Build and release

Project files, packaging manifests, CI, and localization assets.

- [VS solution](https://github.com/vslavik/winsparkle/blob/master/WinSparkle.sln): build root · Primary Visual Studio build entry point. · `WinSparkle.sln`
- [CMake build](https://github.com/vslavik/winsparkle/blob/master/cmake/CMakeLists.txt): build config · Alternative CMake build and packaging path. · `cmake/CMakeLists.txt`
- [NuGet package](https://github.com/vslavik/winsparkle/blob/master/nuget/WinSparkle.nuspec): distribution · NuGet packaging metadata for consumers. · `nuget/WinSparkle.nuspec`
- [Translations](https://github.com/vslavik/winsparkle/blob/master/translations/translations.rc): localization · Localized UI strings and translation resources. · `translations/translations.rc`

## Connections

- Public API → DLL exports: declares · Public API is implemented by exported DLL entry points.
- Version info → NuGet package: versions · Version metadata feeds packaging and distribution identity.
- DLL init → Controller: starts · DLL lifecycle leads into runtime controller setup.
- DLL exports → Settings: configures · Host calls set app identity, feed URL, and keys via the DLL boundary.
- DLL exports → Controller: drives · Exported API triggers the update lifecycle controller.
- Controller → Settings: reads/writes · Controller consults persistent config and update state.
- Controller → Check updates: checks · Controller delegates update discovery to the checker.
- Check updates → Appcast parse: fetches/parses · Update URL is resolved into an appcast manifest and release record.
- Appcast parse → Expat: parses with · XML manifest parsing relies on Expat.
- Appcast parse → Verify sig: provides signature · Parsed enclosure metadata is passed to verification.
- Verify sig → Ed25519: verifies with · Modern signatures use bundled Ed25519 support.
- Verify sig → OpenSSL: verifies with · Legacy compatibility and crypto primitives use OpenSSL.
- Controller → Update UI: prompts · Controller hands accepted updates to visible user interaction.
- Update UI → wxWidgets: built on · UI layer is backed by wxWidgets.
- Controller → Background work: runs on · Background execution keeps update work off the host UI thread.
- Background work → Download: executes · Asynchronous work performs payload retrieval.
- Controller → Installer handoff: handoffs to · Controller delegates install transition after release acceptance.
- Installer handoff → Download: uses · Installer handoff depends on download retrieval.
- Signing tool → Ed25519: produces signatures · CLI tool signs update artifacts for runtime verification.
- Signing tool → OpenSSL: legacy support · Tooling also supports older signing workflows.
- PSDK example → Public API: integrates via · Native sample shows host-side API usage.
- Qt example → Public API: integrates via · Qt sample shows host-side API usage.
- Pascal bindings → Public API: binds to · Pascal bindings wrap the public C API.
- VS solution → Public API: builds · Visual Studio solution builds the core library and public surface.
- CMake build → wxWidgets: configures · CMake path wires third-party dependencies into builds.
- CMake build → Expat: configures · CMake path wires XML dependency into builds.
- CMake build → OpenSSL: configures · CMake path wires crypto dependency into builds.
- NuGet package → Public API: packages · NuGet distribution exposes the public library surface.
- Translations → Update UI: localizes · Translation resources feed the user-facing dialogs.
