# alex-spataru/qsimpleupdater architecture

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

- Interactive diagram: https://gitdiagram.com/alex-spataru/qsimpleupdater
- Repository: https://github.com/alex-spataru/qsimpleupdater

## Overview

QSimpleUpdater is a Qt-based reusable library, not an application. Its purpose is to let a host Qt app check a remote update manifest, compare versions, download an installer or package, and optionally hand control back to the host app for custom install logic.

##### Public API boundary
- The library’s public surface is concentrated in `include/QSimpleUpdater.h`.
- Consumers integrate it either through CMake (`CMakeLists.txt`, `QSimpleUpdaterConfig.cmake.in`) or qmake (`QSimpleUpdater.pro`, `QSimpleUpdater.pri`).
- The README’s examples indicate the main entry point is a singleton-style manager accessed by update-definition URL.

##### Core orchestration layer
- `src/QSimpleUpdater.cpp` is the top-level façade that application code talks to.
- It appears responsible for per-update-definition configuration such as enabling notifications, downloader behavior, module names/versions, and custom install procedures.
- Architecturally, this is the boundary between host application code and the update subsystem.

##### Per-update state and business logic
- `src/Updater.cpp` / `src/Updater.h` are the main stateful engine for a single update stream.
- The README’s “multiple modules” model strongly suggests each update manifest URL maps to one updater instance holding its own module metadata, version, and policy flags.
- This layer is where manifest parsing, version comparison, and update decision-making live.

##### Network-driven update flow
- The update flow is: fetch JSON manifest → read platform-specific entry → compare remote vs local version → decide whether to notify, download, or open a URL.
- The manifest schema in the README is the primary data contract with the server.
- Network transport is constrained to HTTP/HTTPS only, so the update subsystem is centered around remote file retrieval rather than general-purpose protocol handling.

##### Downloader and install path
- `src/Downloader.cpp` / `src/Downloader.h` plus `src/Downloader.ui` implement the built-in download UI and progress experience.
- This is the component that turns a remote `download-url` into a local file and signals completion.
- It is also the main handoff point for either automatic install behavior or custom install handling from the host application.

##### Authentication and access control
- `src/AuthenticateDialog.cpp` / `.h` / `.ui` provide a dedicated UI for authenticated downloads.
- This indicates the downloader supports protected endpoints and user credential entry, which is a separate concern from update logic itself.

##### Versioning subsystem
- Version comparison is a distinct concern and is explicitly covered by `tests/Test_Versioning.h`.
- The README shows semantic-version-aware behavior, including pre-release ordering and optional `v` prefix handling.
- This is important for architecture because “update available” is derived from version semantics, not just string comparison.

##### Platform-specific manifest routing
- The update definition file contains keys like `windows`, `osx`, `linux`, `ios`, and `android`, with support for custom platform keys.
- That means one manifest can serve multiple platforms while keeping platform-specific download URLs, open URLs, and changelogs.
- The platform-selection logic is a key decision point inside the updater engine.

##### Resource and packaging layer
- `etc/resources/qsimpleupdater.qrc` bundles library assets; `etc/resources/version.rc.in` suggests Windows version metadata integration.
- These files are part of the distribution/branding layer rather than the update algorithm itself.

##### Tutorial as reference host application
- `tutorial/` is a sample Qt app that demonstrates integration and end-to-end behavior.
- It has its own UI (`tutorial/src/Window.ui`) and update manifest example (`tutorial/definitions/updates.json`).
- Architecturally, this is the consumer-side reference, showing how the library is embedded in a real application.

##### Tests and verification
- `tests/` contains unit-style coverage for downloader behavior, updater behavior, public API behavior, and versioning.
- This suggests the repository treats the library as a set of independently testable subsystems rather than only integration-tested UI.
- `tests/main.cpp` and `Tests.pro` indicate a separate test executable.

##### Build, CI, and repository boundaries
- The repo supports both CMake and qmake, which matters for how the library is consumed and packaged.
- GitHub Actions (`.github/workflows/main.yml`) provides CI build validation.
- The project is structured as a library with optional tutorial/tests, not as a single monolithic executable.

Overall, the architecture is: host Qt app → public `QSimpleUpdater` API → per-URL `Updater` state and version logic → network fetch of JSON manifest → optional `Downloader`/`AuthenticateDialog` UI → downloaded file or custom install callback.

Main entry points: [`tests/main.cpp`](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/main.cpp) (Test suite), [`src/Downloader.cpp`](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Downloader.cpp) (Downloader), [`src/QSimpleUpdater.cpp`](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/QSimpleUpdater.cpp) (Facade), [`tutorial/src/main.cpp`](https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/src/main.cpp) (Tutorial app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public_api["Public API"]
  node_include_api["QSimpleUpdater API<br/>public header<br/>[QSimpleUpdater.h]"]
  node_cmake_build["CMake build<br/>build integration<br/>[CMakeLists.txt]"]
  node_qmake_build["qmake build<br/>build integration<br/>[QSimpleUpdater.pro]"]
end

subgraph group_group_core["Core Engine"]
  node_qsu_facade["Facade<br/>[QSimpleUpdater.cpp]"]
  node_updater_engine["Updater engine<br/>stateful updater<br/>[Updater.cpp]"]
  node_updater_header["Updater API<br/>engine header<br/>[Updater.h]"]
  node_manifest_flow(("Manifest flow<br/>update logic"))
  node_version_logic{{"Versioning<br/>compare logic<br/>[Test_Versioning.h]"}}
end

subgraph group_group_ui["UI Flow"]
  node_downloader["Downloader<br/>download client<br/>[Downloader.cpp]"]
  node_downloader_ui["Download UI<br/>Qt dialog<br/>[Downloader.ui]"]
  node_auth_dialog["Auth dialog<br/>credentials UI"]
  node_auth_ui["Auth UI<br/>Qt dialog"]
end

subgraph group_group_packaging["Packaging"]
  node_cmake_config["CMake config<br/>package config"]
  node_resources_qrc["Library assets<br/>resource bundle<br/>[qsimpleupdater.qrc]"]
  node_version_rc["Windows metadata<br/>resource template<br/>[version.rc.in]"]
end

subgraph group_group_examples["Examples"]
  node_tutorial_app["Tutorial app<br/>sample host<br/>[main.cpp]"]
  node_tutorial_window["Tutorial window<br/>sample UI<br/>[Window.cpp]"]
  node_tutorial_manifest["Sample manifest<br/>example data<br/>[updates.json]"]
end

subgraph group_group_tests["Tests"]
  node_test_suite["Test suite<br/>test runner<br/>[main.cpp]"]
  node_test_api["API tests<br/>unit tests"]
  node_test_updater["Updater tests<br/>unit tests<br/>[Test_Updater.h]"]
  node_test_downloader["Downloader tests<br/>unit tests<br/>[Test_Downloader.h]"]
end

node_include_api -->|"declares"| node_qsu_facade
node_qsu_facade -->|"creates/owns"| node_updater_engine
node_qsu_facade -->|"coordinates"| node_manifest_flow
node_updater_engine -->|"uses"| node_manifest_flow
node_manifest_flow -->|"compares"| node_version_logic
node_manifest_flow -->|"starts"| node_downloader
node_downloader -->|"renders"| node_downloader_ui
node_downloader -->|"requests auth"| node_auth_dialog
node_auth_dialog -->|"renders"| node_auth_ui
node_downloader -->|"notifies"| node_version_logic
node_tutorial_app -->|"consumes"| node_qsu_facade
node_tutorial_app -->|"implements"| node_tutorial_window
node_tutorial_app -->|"uses"| node_tutorial_manifest
node_test_suite -->|"runs"| node_test_api
node_test_suite -->|"runs"| node_test_updater
node_test_suite -->|"runs"| node_test_downloader
node_test_suite -->|"verifies"| node_version_logic
node_cmake_build -->|"packages"| node_include_api
node_qmake_build -->|"packages"| node_include_api
node_cmake_config -->|"supports"| node_cmake_build
node_resources_qrc -->|"bundles"| node_downloader_ui
node_resources_qrc -->|"bundles"| node_auth_ui
node_version_rc -->|"complements"| node_resources_qrc

click node_include_api "https://github.com/alex-spataru/qsimpleupdater/blob/master/include/QSimpleUpdater.h"
click node_cmake_build "https://github.com/alex-spataru/qsimpleupdater/blob/master/CMakeLists.txt"
click node_qmake_build "https://github.com/alex-spataru/qsimpleupdater/blob/master/QSimpleUpdater.pro"
click node_cmake_config "https://github.com/alex-spataru/qsimpleupdater/blob/master/QSimpleUpdaterConfig.cmake.in"
click node_qsu_facade "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/QSimpleUpdater.cpp"
click node_updater_engine "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Updater.cpp"
click node_updater_header "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Updater.h"
click node_version_logic "https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Versioning.h"
click node_downloader "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Downloader.cpp"
click node_downloader_ui "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Downloader.ui"
click node_auth_dialog "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/AuthenticateDialog.cpp"
click node_auth_ui "https://github.com/alex-spataru/qsimpleupdater/blob/master/src/AuthenticateDialog.ui"
click node_resources_qrc "https://github.com/alex-spataru/qsimpleupdater/blob/master/etc/resources/qsimpleupdater.qrc"
click node_version_rc "https://github.com/alex-spataru/qsimpleupdater/blob/master/etc/resources/version.rc.in"
click node_tutorial_app "https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/src/main.cpp"
click node_tutorial_window "https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/src/Window.cpp"
click node_tutorial_manifest "https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/definitions/updates.json"
click node_test_suite "https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/main.cpp"
click node_test_api "https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_QSimpleUpdater.h"
click node_test_updater "https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Updater.h"
click node_test_downloader "https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Downloader.h"

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_include_api,node_cmake_build,node_qmake_build toneBlue
class node_qsu_facade,node_updater_engine,node_updater_header,node_manifest_flow,node_version_logic toneAmber
class node_downloader,node_downloader_ui,node_auth_dialog,node_auth_ui toneMint
class node_cmake_config,node_resources_qrc,node_version_rc toneRose
class node_tutorial_app,node_tutorial_window,node_tutorial_manifest toneIndigo
class node_test_suite,node_test_api,node_test_updater,node_test_downloader toneTeal
```

## Components

### Public API

Headers and integration surfaces used by host Qt applications.

- [QSimpleUpdater API](https://github.com/alex-spataru/qsimpleupdater/blob/master/include/QSimpleUpdater.h): public header · Main public entry point for consumers. · `include/QSimpleUpdater.h`
- [CMake build](https://github.com/alex-spataru/qsimpleupdater/blob/master/CMakeLists.txt): build integration · CMake entrypoint for consumers and packaging. · `CMakeLists.txt`
- [qmake build](https://github.com/alex-spataru/qsimpleupdater/blob/master/QSimpleUpdater.pro): build integration · qmake project and .pri consumption path. · `QSimpleUpdater.pro`

### Core Engine

Runtime orchestration, manifest handling, version decisions, and download flow.

- [Facade](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/QSimpleUpdater.cpp): library facade · Top-level API object used by host applications. · `src/QSimpleUpdater.cpp`
- [Updater engine](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Updater.cpp): stateful updater · Per-manifest state, policies, and update decisions. · `src/Updater.cpp`
- [Updater API](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Updater.h): engine header · Public contract for the per-update stream engine. · `src/Updater.h`
- **Manifest flow**: update logic · Fetches manifest data and selects platform-specific entries.
- [Versioning](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Versioning.h): compare logic · Semantic version comparison and release ordering. · `tests/Test_Versioning.h`

### UI Flow

Dialogs and widgets used during authentication and downloading.

- [Downloader](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Downloader.cpp): download client · Downloads installer or package and tracks progress. · `src/Downloader.cpp`
- [Download UI](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/Downloader.ui): Qt dialog · Built-in progress and download experience. · `src/Downloader.ui`
- [Auth dialog](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/AuthenticateDialog.cpp): credentials UI · Authentication prompt for protected downloads. · `src/AuthenticateDialog.cpp`
- [Auth UI](https://github.com/alex-spataru/qsimpleupdater/blob/master/src/AuthenticateDialog.ui): Qt dialog · Credential entry form used by the downloader. · `src/AuthenticateDialog.ui`

### Packaging

Build and resource files that package the library for consumption.

- [CMake config](https://github.com/alex-spataru/qsimpleupdater/blob/master/QSimpleUpdaterConfig.cmake.in): package config · Generated package configuration template. · `QSimpleUpdaterConfig.cmake.in`
- [Library assets](https://github.com/alex-spataru/qsimpleupdater/blob/master/etc/resources/qsimpleupdater.qrc): resource bundle · Packaged UI assets and embedded resources. · `etc/resources/qsimpleupdater.qrc`
- [Windows metadata](https://github.com/alex-spataru/qsimpleupdater/blob/master/etc/resources/version.rc.in): resource template · Windows version and branding resource template. · `etc/resources/version.rc.in`

### Examples

Tutorial host application demonstrating integration.

- [Tutorial app](https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/src/main.cpp): sample host · Reference Qt application showing integration. · `tutorial/src/main.cpp`
- [Tutorial window](https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/src/Window.cpp): sample UI · Example host application window and integration code. · `tutorial/src/Window.cpp`
- [Sample manifest](https://github.com/alex-spataru/qsimpleupdater/blob/master/tutorial/definitions/updates.json): example data · Example update definition used by the tutorial. · `tutorial/definitions/updates.json`

### Tests

Executable test coverage for the library subsystems.

- [Test suite](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/main.cpp): test runner · Dedicated executable for library verification. · `tests/main.cpp`
- [API tests](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_QSimpleUpdater.h): unit tests · Coverage for the public facade behavior. · `tests/Test_QSimpleUpdater.h`
- [Updater tests](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Updater.h): unit tests · Coverage for updater behavior and decisions. · `tests/Test_Updater.h`
- [Downloader tests](https://github.com/alex-spataru/qsimpleupdater/blob/master/tests/Test_Downloader.h): unit tests · Coverage for download flow behavior. · `tests/Test_Downloader.h`

## Connections

- QSimpleUpdater API → Facade: declares · Public header exposes the main library surface.
- Facade → Updater engine: creates/owns · Facade manages per-update updater instances.
- Facade → Manifest flow: coordinates · Top-level API triggers manifest retrieval and update checks.
- Updater engine → Manifest flow: uses · Updater parses manifests and selects the platform-specific payload.
- Manifest flow → Versioning: compares · Remote and local versions are compared to decide update availability.
- Manifest flow → Downloader: starts · When an update is accepted, the updater hands off to download.
- Downloader → Download UI: renders · Downloader presents the built-in progress UI.
- Downloader → Auth dialog: requests auth · Protected downloads route through the authentication dialog.
- Auth dialog → Auth UI: renders · Dialog UI gathers credentials.
- Downloader → Versioning: notifies · Download completion feeds into install/update decision flow.
- Tutorial app → Facade: consumes · Sample host application integrates the library through the facade.
- Tutorial app → Tutorial window: implements · Tutorial window contains the sample app behavior.
- Tutorial app → Sample manifest: uses · Sample app points at an example manifest.
- Test suite → API tests: runs · Test executable includes API coverage.
- Test suite → Updater tests: runs · Test executable includes updater coverage.
- Test suite → Downloader tests: runs · Test executable includes downloader coverage.
- Test suite → Versioning: verifies · Version semantics are validated separately.
- CMake build → QSimpleUpdater API: packages · CMake build exports the public header.
- qmake build → QSimpleUpdater API: packages · qmake build exposes the same public API.
- CMake config → CMake build: supports · Package config template supports CMake consumption.
- Library assets → Download UI: bundles · Resource bundle packages UI assets.
- Library assets → Auth UI: bundles · Resource bundle packages dialog assets.
- Windows metadata → Library assets: complements · Windows metadata complements packaged resources.