# mendersoftware/mender architecture

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

- Interactive diagram: https://gitdiagram.com/mendersoftware/mender
- Repository: https://github.com/mendersoftware/mender

## Overview

#### Purpose and deliverables
This is the C++ Mender device client for secure OTA updates on embedded Linux. It builds two operational binaries: `mender-update` for managed/standalone deployments and `mender-auth`/`mender-authd` for device authentication and credential services. Top-level build and installation wiring is in `CMakeLists.txt`, `main.cmake`, and `src/CMakeLists.txt`.

#### Process entry points and operating modes
`src/mender-update/main.cpp` dispatches CLI, daemon, and standalone update paths. Managed mode runs a persistent daemon that polls/communicates with the Mender backend; standalone mode applies a locally supplied artifact without a server. `src/mender-auth/main.cpp` starts authentication functions and its IPC-facing service. systemd integration deploys them as separate services via `support/mender-updated.service` and `support/mender-authd.service`.

#### Update orchestration state machine
The update daemon owns the durable deployment lifecycle—synchronization, download, installation, reboot/commit, and failure handling—through explicit states and events. Key boundaries are `src/mender-update/daemon/state_machine/state_machine.cpp`, `src/mender-update/daemon/states.cpp`, and `src/mender-update/deployments/deployments.cpp`. State-script execution lets device integrators hook lifecycle transitions, while bootloader/A/B partition integration outside this repository provides rollback semantics.

#### Artifact validation and execution pipeline
Artifacts are parsed as Mender Artifact v3 archives: read TAR content, parse header/manifest/payload metadata, verify manifest signatures/checksums, then select and execute payload handling. The core is `src/artifact/artifact.cpp`, `src/artifact/v3/manifest/manifest.cpp`, and `src/artifact/v3/payload/payload.cpp`. Archive and hashing adapters use libarchive and OpenSSL (`src/artifact/tar/platform/libarchive/tar.cpp`, `src/artifact/sha/platform/openssl/sha.cpp`). Artifact scripts are executed through `src/artifact/v3/scripts/executor.cpp`.

#### Update Modules and device-side application
Non-rootfs artifact payloads are delegated to externally installed Update Modules, invoked with the v3 module protocol and filesystem operations. This adapter boundary is `src/mender-update/update_module/v3/update_module.cpp`, `src/mender-update/update_module/v3/update_module_download.cpp`, and `src/mender-update/update_module/v3/platform/c++17/update_module_call.cpp`. Bundled reference modules live under `support/modules/`, including `support/modules/rootfs-image` and `support/modules/directory`.

#### Authentication, transport, and server boundary
The client communicates with Mender backend APIs over HTTP(S), authenticating devices and retaining credentials/keys. Shared API client interfaces are in `src/api/client.cpp` and `src/api/auth/auth.cpp`; auth service behavior is in `src/mender-auth/api/auth/auth.cpp`. `mender-auth` exposes local authentication/HTTP forwarding over IPC, optionally D-Bus, through `src/mender-auth/ipc/server.cpp`, `src/mender-auth/http_forwarder/http_forwarder.cpp`, and `src/api/auth/platform/dbus/auth.cpp`. The backend, artifact storage, and cloud integrations are external services, not implemented here.

#### Shared runtime and persistence
`src/common/` supplies platform-isolated facilities used by both executables: asynchronous Boost event/HTTP transport, OpenSSL crypto, local key-value persistence, subprocess execution, filesystem access, structured logging, and optional D-Bus. Architecturally central implementations include `src/common/http/platform/beast/http.cpp`, `src/common/key_value_database/platform/lmdb/lmdb.cpp`, and `src/common/platform/dbus/asio_libdbus/dbus.cpp`. Configuration, identity, and inventory feed enrollment and deployment requests through `src/client_shared/conf/conf.cpp`, `src/client_shared/identity_parser/identity_parser.cpp`, and `src/mender-update/inventory.cpp`.

#### Build targets and portability
CMake builds a native C++ client with Boost, libarchive, LMDB, OpenSSL, D-Bus, and systemd dependencies. Platform seams permit POSIX/Linux and experimental QNX variants; examples include `cmake/qnx.cmake`, `src/common/io/platform/posix/io.cpp`, and `cmake/aarch64.cmake`. QNX can disable D-Bus and LMDB and embed authentication, preserving the update core behind these runtime substitutions.

Main entry points: [`src/mender-update/daemon/state_machine/state_machine.cpp`](https://github.com/mendersoftware/mender/blob/master/src/mender-update/daemon/state_machine/state_machine.cpp) (Update state machine), [`src/mender-auth/api/auth/auth.cpp`](https://github.com/mendersoftware/mender/blob/master/src/mender-auth/api/auth/auth.cpp) (Authentication API), [`src/mender-update/main.cpp`](https://github.com/mendersoftware/mender/blob/master/src/mender-update/main.cpp) (mender-update), [`src/mender-update/deployments/deployments.cpp`](https://github.com/mendersoftware/mender/blob/master/src/mender-update/deployments/deployments.cpp) (Deployment coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; deployment"]
  node_cmake["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_systemd["systemd services<br/>service units"]
end

subgraph group_update["Update client"]
  node_update_entry["mender-update<br/>process entry<br/>[main.cpp]"]
  node_update_daemon{{"Update state machine<br/>deployment lifecycle<br/>[state_machine.cpp]"}}
  node_deployments["Deployment coordination<br/>backend deployment client<br/>[deployments.cpp]"]
  node_inventory["Identity &amp; inventory<br/>device metadata<br/>[inventory.cpp]"]
  node_update_modules["Update Module adapter<br/>v3 module protocol<br/>[update_module.cpp]"]
end

subgraph group_artifact["Artifact pipeline"]
  node_artifact_core["Artifact v3 parser<br/>archive pipeline<br/>[artifact.cpp]"]
  node_manifest["Manifest verification<br/>signature &amp; checksum validation<br/>[manifest.cpp]"]
  node_payload["Payload &amp; scripts<br/>payload executor<br/>[payload.cpp]"]
end

subgraph group_auth["Authentication service"]
  node_auth_entry["mender-auth / authd<br/>process entry<br/>[main.cpp]"]
  node_auth_service["Authentication API<br/>credential service<br/>[auth.cpp]"]
  node_ipc["IPC &amp; HTTP forwarding<br/>local service boundary<br/>[server.cpp]"]
end

subgraph group_runtime["Shared runtime"]
  node_api_client["Shared API client<br/>HTTPS API interface<br/>[client.cpp]"]
  node_http["Async HTTP transport<br/>Boost.Beast adapter<br/>[http.cpp]"]
  node_persistence[("Credential persistence<br/>LMDB key-value store<br/>[lmdb.cpp]")]
  node_platform["Platform seams<br/>POSIX/QNX runtime<br/>[qnx.cmake]"]
end

subgraph group_external["External boundaries"]
  node_backend(("Mender backend<br/>external cloud API"))
  node_modules["Installed Update Modules<br/>external device handlers"]
  node_bootloader["Bootloader / A-B partitions<br/>external rollback boundary"]
end

node_cmake -->|"builds"| node_update_entry
node_cmake -->|"builds"| node_auth_entry
node_systemd -->|"runs"| node_update_entry
node_systemd -->|"runs"| node_auth_entry
node_update_entry -->|"managed mode"| node_update_daemon
node_update_daemon -->|"synchronizes"| node_deployments
node_inventory -->|"supplies metadata"| node_deployments
node_deployments -->|"uses"| node_api_client
node_update_daemon -->|"downloads and validates"| node_artifact_core
node_artifact_core -->|"verifies"| node_manifest
node_manifest -->|"authorizes payload"| node_payload
node_payload -->|"delegates non-rootfs"| node_update_modules
node_update_modules -->|"invokes"| node_modules
node_update_daemon -->|"reboot / commit"| node_bootloader
node_auth_entry -->|"hosts"| node_auth_service
node_auth_service -->|"serves locally"| node_ipc
node_auth_service -->|"stores credentials"| node_persistence
node_auth_service -->|"authenticates through"| node_api_client
node_api_client -->|"uses"| node_http
node_http -->|"HTTPS"| node_backend
node_platform -.->|"selects runtime variants"| node_http
node_platform -.->|"may replace or disable"| node_persistence

click node_cmake "https://github.com/mendersoftware/mender/blob/master/CMakeLists.txt"
click node_systemd "https://github.com/mendersoftware/mender/blob/master/support/mender-updated.service"
click node_update_entry "https://github.com/mendersoftware/mender/blob/master/src/mender-update/main.cpp"
click node_update_daemon "https://github.com/mendersoftware/mender/blob/master/src/mender-update/daemon/state_machine/state_machine.cpp"
click node_deployments "https://github.com/mendersoftware/mender/blob/master/src/mender-update/deployments/deployments.cpp"
click node_inventory "https://github.com/mendersoftware/mender/blob/master/src/mender-update/inventory.cpp"
click node_update_modules "https://github.com/mendersoftware/mender/blob/master/src/mender-update/update_module/v3/update_module.cpp"
click node_artifact_core "https://github.com/mendersoftware/mender/blob/master/src/artifact/artifact.cpp"
click node_manifest "https://github.com/mendersoftware/mender/blob/master/src/artifact/v3/manifest/manifest.cpp"
click node_payload "https://github.com/mendersoftware/mender/blob/master/src/artifact/v3/payload/payload.cpp"
click node_auth_entry "https://github.com/mendersoftware/mender/blob/master/src/mender-auth/main.cpp"
click node_auth_service "https://github.com/mendersoftware/mender/blob/master/src/mender-auth/api/auth/auth.cpp"
click node_ipc "https://github.com/mendersoftware/mender/blob/master/src/mender-auth/ipc/server.cpp"
click node_api_client "https://github.com/mendersoftware/mender/blob/master/src/api/client.cpp"
click node_http "https://github.com/mendersoftware/mender/blob/master/src/common/http/platform/beast/http.cpp"
click node_persistence "https://github.com/mendersoftware/mender/blob/master/src/common/key_value_database/platform/lmdb/lmdb.cpp"
click node_platform "https://github.com/mendersoftware/mender/blob/master/cmake/qnx.cmake"

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_cmake,node_systemd toneBlue
class node_update_entry,node_update_daemon,node_deployments,node_inventory,node_update_modules toneAmber
class node_artifact_core,node_manifest,node_payload toneMint
class node_auth_entry,node_auth_service,node_ipc toneRose
class node_api_client,node_http,node_persistence,node_platform toneIndigo
class node_backend,node_modules,node_bootloader toneTeal
```

## Components

### Build & deployment

- [CMake build](https://github.com/mendersoftware/mender/blob/master/CMakeLists.txt): build system · Builds native binaries and selects platform dependencies. · `CMakeLists.txt`
- [systemd services](https://github.com/mendersoftware/mender/blob/master/support/mender-updated.service): service units · Runs update and authentication daemons separately. · `support/mender-updated.service`

### Update client

- [mender-update](https://github.com/mendersoftware/mender/blob/master/src/mender-update/main.cpp): process entry · Dispatches managed daemon, CLI, and standalone update modes. · `src/mender-update/main.cpp`
- [Update state machine](https://github.com/mendersoftware/mender/blob/master/src/mender-update/daemon/state_machine/state_machine.cpp): deployment lifecycle · Owns durable synchronization, install, reboot, commit, and failure transitions. · `src/mender-update/daemon/state_machine/state_machine.cpp`
- [Deployment coordination](https://github.com/mendersoftware/mender/blob/master/src/mender-update/deployments/deployments.cpp): backend deployment client · `src/mender-update/deployments/deployments.cpp`
- [Identity & inventory](https://github.com/mendersoftware/mender/blob/master/src/mender-update/inventory.cpp): device metadata · Feeds enrollment and deployment requests. · `src/mender-update/inventory.cpp`
- [Update Module adapter](https://github.com/mendersoftware/mender/blob/master/src/mender-update/update_module/v3/update_module.cpp): v3 module protocol · Delegates non-rootfs payload operations to installed modules. · `src/mender-update/update_module/v3/update_module.cpp`

### Artifact pipeline

- [Artifact v3 parser](https://github.com/mendersoftware/mender/blob/master/src/artifact/artifact.cpp): archive pipeline · Parses artifact header, manifest, and payload metadata. · `src/artifact/artifact.cpp`
- [Manifest verification](https://github.com/mendersoftware/mender/blob/master/src/artifact/v3/manifest/manifest.cpp): signature & checksum validation · `src/artifact/v3/manifest/manifest.cpp`
- [Payload & scripts](https://github.com/mendersoftware/mender/blob/master/src/artifact/v3/payload/payload.cpp): payload executor · Selects payload handlers and runs artifact lifecycle scripts. · `src/artifact/v3/payload/payload.cpp`

### Authentication service

- [mender-auth / authd](https://github.com/mendersoftware/mender/blob/master/src/mender-auth/main.cpp): process entry · Starts device authentication and local credential services. · `src/mender-auth/main.cpp`
- [Authentication API](https://github.com/mendersoftware/mender/blob/master/src/mender-auth/api/auth/auth.cpp): credential service · `src/mender-auth/api/auth/auth.cpp`
- [IPC & HTTP forwarding](https://github.com/mendersoftware/mender/blob/master/src/mender-auth/ipc/server.cpp): local service boundary · Exposes authentication and HTTP forwarding to local clients. · `src/mender-auth/ipc/server.cpp`

### Shared runtime

- [Shared API client](https://github.com/mendersoftware/mender/blob/master/src/api/client.cpp): HTTPS API interface · Provides common backend and authentication client interfaces. · `src/api/client.cpp`
- [Async HTTP transport](https://github.com/mendersoftware/mender/blob/master/src/common/http/platform/beast/http.cpp): Boost.Beast adapter · `src/common/http/platform/beast/http.cpp`
- [Credential persistence](https://github.com/mendersoftware/mender/blob/master/src/common/key_value_database/platform/lmdb/lmdb.cpp): LMDB key-value store · `src/common/key_value_database/platform/lmdb/lmdb.cpp`
- [Platform seams](https://github.com/mendersoftware/mender/blob/master/cmake/qnx.cmake): POSIX/QNX runtime · Substitutes runtime facilities such as D-Bus and LMDB by target platform. · `cmake/qnx.cmake`

### External boundaries

- **Mender backend**: external cloud API · Provides device authentication, deployments, and artifact storage.
- **Installed Update Modules**: external device handlers · Reference rootfs-image and directory modules are bundled for installation.
- **Bootloader / A-B partitions**: external rollback boundary · Performs platform-specific reboot and rollback semantics.

## Connections

- CMake build → mender-update: builds
- CMake build → mender-auth / authd: builds
- systemd services → mender-update: runs
- systemd services → mender-auth / authd: runs
- mender-update → Update state machine: managed mode
- Update state machine → Deployment coordination: synchronizes
- Identity & inventory → Deployment coordination: supplies metadata
- Deployment coordination → Shared API client: uses
- Update state machine → Artifact v3 parser: downloads and validates
- Artifact v3 parser → Manifest verification: verifies
- Manifest verification → Payload & scripts: authorizes payload
- Payload & scripts → Update Module adapter: delegates non-rootfs
- Update Module adapter → Installed Update Modules: invokes
- Update state machine → Bootloader / A-B partitions: reboot / commit
- mender-auth / authd → Authentication API: hosts
- Authentication API → IPC & HTTP forwarding: serves locally
- Authentication API → Credential persistence: stores credentials
- Authentication API → Shared API client: authenticates through
- Shared API client → Async HTTP transport: uses
- Async HTTP transport → Mender backend: HTTPS
- Platform seams → Async HTTP transport: selects runtime variants
- Platform seams → Credential persistence: may replace or disable
