# azure/iot-hub-device-update architecture

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

- Interactive diagram: https://gitdiagram.com/azure/iot-hub-device-update
- Repository: https://github.com/azure/iot-hub-device-update

## Overview

##### Project Type and Purpose
- This is a native-agent project (“Device Update for IoT Hub”) written in C/C++ with a CLI tool, libraries, extensions and build/deployment scripts.
- Purpose: run on an edge or IoT device, retrieve OTA updates from Azure IoT Hub’s Device Update service, orchestrate update workflows, apply updates via pluggable handlers, then report status back to IoT Hub.

##### File Structure Analysis
Top-level components:
- cmake, vcpkg.json, CMakeLists.txt – cross-platform build & dependency definitions.
- src/agent – the core agent implementation (main.c, health management, shutdown service).
- src/adu-shell – CLI (“adu” shell) for local/manual update operations.
- src/communication_* – abstractions and IoT Hub manager implementation.
- src/adu_workflow, src/agent_orchestration, src/rootkey_workflow – orchestrate update life-cycle, cryptographic root-key handling.
- src/extensions – plugin framework: content downloaders, download handlers, component enumerators, step handlers, update-manifest handlers, extension manager.
- src/diagnostics_component – diagnostics workflows & helpers.
- src/logging – zlog integration.
- src/libaducpal, src/platform_layers – platform-abstraction layer (Linux/Windows).
- src/utils – common utilities (parsing, file, crypto, retry, reporting, D2C messaging, etc.).
- scripts & tools – CI/CD, Docker, package build, tests, sample tools.
- docs – architecture reference and how-to.

##### README Insights
- Confirms it’s the “reference agent” that talks to Azure IoT Hub’s Device Update service.
- Build/test instructions illustrating CLI, agent install, valgrind testing.

##### Main Components
a. Agent Core – process hosting workflows, extension loader and orchestrator.
b. CLI (adu-shell) – user-facing shell that invokes the Agent Core APIs.
c. Workflow Engine (agent_orchestration + adu_workflow + rootkey_workflow) – state machine managing update stages (download, validation, install, reboot, rollback).
d. Communication Layer – abstraction + IoT Hub communication manager for twin-desired/property subscriptions and D2C reporting.
e. Extension Manager & Extensions – dynamically loaded libraries for:
- Component Enumeration
- Content Downloading (curl, delivery optimization)
- Download Handlers (delta, full payload)
- Step Handlers (APT, script, wim, swupdate, simulator)
- Update-Manifest Handlers
f. Diagnostics Component – run diagnostic steps, upload logs.
g. Logging Subsystem – zlog integration.
h. Platform Abstraction – libaducpal + OS-specific layers (Linux/Windows).
i. Utilities – collection of helper libraries (config, crypto, parser, retry, file, URL, workflow data, etc.).

##### Interactions & Data Flows
- Agent Core ↔ IoT Hub (via Communication Layer): subscribe to desired properties, receive update instructions, send reported state & diagnostics.
- Agent Core → Workflow Engine: start new update workflow on instruction or CLI command.
- Workflow Engine → Extension Manager: load appropriate extension for each workflow stage (download, install, etc.).
- Extension → Platform Layer and Utils: perform file I/O, process spawning, cryptographic checks.
- Diagnostics Component invoked by Agent Core or workflows to gather device info and send back via Communication Layer.
- CLI → Agent Core APIs (IPC or direct function call) for manual operations.

##### Architectural Patterns & Principles
- Plugin architecture: extensions loaded at runtime via a shared-lib abstraction (shared_lib, extension_manager).
- Layered separation: presentation (CLI), orchestration (workflow), communication, extensions, platform abstraction, utilities.
- Dependency Injection via config files and CMake symbol exports.
- Event-driven state machine for workflows.

##### Technologies & Frameworks
- CMake + Ninja / Make – build system
- zlog – logging
- Parson JSON – lightweight JSON parsing
- Azure IoT Hub SDK – communication manager (client handles)
- C99, C++17 – language features
- Docker / Azure Pipelines / Terraform / Packer – CI/CD & E2E test infra

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Cloud
    Cloud["Azure IoT Hub / Device Update Service"]:::external

    %% Communication Layer
    subgraph "Communication Layer" 
        CommAbst["Abstraction Layer"]:::comm
        CommMgr["IoT Hub Comm Manager"]:::comm
    end

    %% Core
    subgraph "Agent Core" 
        AgentCore["Agent Core"]:::core
    end

    %% Workflow Engine
    subgraph "Workflow Engine" 
        Orchestration["agent_orchestration"]:::core
        Workflow["adu_workflow"]:::core
        RootKey["rootkey_workflow"]:::core
    end

    %% Extension Manager & Extensions
    subgraph "Extension Manager & Extensions"
        ExtMgr["extension_manager"]:::ext
        SharedLib["shared_lib"]:::ext
        subgraph "Extensions"
            CompEnum["component_enumerators"]:::ext
            ContentDL["content_downloaders"]:::ext
            DLHandlers["download_handlers"]:::ext
            StepHandlers["step_handlers"]:::ext
            ManifestHandlers["update_manifest_handlers"]:::ext
        end
    end

    %% Platform & Utilities
    subgraph "Platform Abstraction" 
        PAL["libaducpal"]:::util
        LinuxPAL["linux_platform_layer"]:::util
        WindowsPAL["windows_platform_layer"]:::util
    end

    subgraph "Utilities" 
        Utils["Utilities (config, crypto, file, retry, etc.)"]:::util
    end

    %% CLI
    CLI["adu-shell (CLI)"]:::cli

    %% Diagnostics
    Diagnostics["Diagnostics Component"]:::diag

    %% Logging
    Logging["Logging Subsystem"]:::log

    %% Build & CI side panel
    subgraph "Build & CI" 
        CMake["CMake & vcpkg"]:::side
        CI["CI Scripts & Docker"]:::side
    end

    %% Connections
    Cloud -->|"desired properties\nupdate instructions"| CommMgr
    CommMgr -->|"notify"| AgentCore
    AgentCore -->|"invoke"| Orchestration
    Orchestration -->|"exec stages"| ExtMgr
    ExtMgr --> SharedLib
    ExtMgr --> CompEnum
    ExtMgr --> ContentDL
    ExtMgr --> DLHandlers
    ExtMgr --> StepHandlers
    ExtMgr --> ManifestHandlers
    SharedLib --> PAL
    SharedLib --> Utils
    CompEnum --> PAL
    ContentDL --> PAL
    DLHandlers --> Utils
    StepHandlers --> PAL
    ManifestHandlers --> Utils
    Orchestration --> Workflow
    Workflow --> RootKey
    CLI -->|"CLI command"| AgentCore
    AgentCore -->|"send telemetry\ndiagnostics"| CommMgr
    Diagnostics -->|"gather/send"| CommMgr
    AgentCore -->|"log events"| Logging

    %% Click events
    click AgentCore "https://github.com/azure/iot-hub-device-update/tree/develop/src/agent"
    click CLI "https://github.com/azure/iot-hub-device-update/tree/develop/src/adu-shell"
    click Orchestration "https://github.com/azure/iot-hub-device-update/tree/develop/src/agent_orchestration"
    click Workflow "https://github.com/azure/iot-hub-device-update/tree/develop/src/adu_workflow"
    click RootKey "https://github.com/azure/iot-hub-device-update/tree/develop/src/rootkey_workflow"
    click CommAbst "https://github.com/azure/iot-hub-device-update/tree/develop/src/communication_abstraction"
    click CommMgr "https://github.com/azure/iot-hub-device-update/tree/develop/src/communication_managers/iothub_communication_manager"
    click ExtMgr "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/extension_manager"
    click SharedLib "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/shared_lib"
    click CompEnum "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/component_enumerators"
    click ContentDL "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/content_downloaders"
    click DLHandlers "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/download_handlers"
    click StepHandlers "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/step_handlers"
    click ManifestHandlers "https://github.com/azure/iot-hub-device-update/tree/develop/src/extensions/update_manifest_handlers"
    click Diagnostics "https://github.com/azure/iot-hub-device-update/tree/develop/src/diagnostics_component"
    click Logging "https://github.com/azure/iot-hub-device-update/tree/develop/src/logging"
    click PAL "https://github.com/azure/iot-hub-device-update/tree/develop/src/libaducpal"
    click LinuxPAL "https://github.com/azure/iot-hub-device-update/tree/develop/src/platform_layers/linux_platform_layer"
    click WindowsPAL "https://github.com/azure/iot-hub-device-update/tree/develop/src/platform_layers/windows_platform_layer"

    %% Styles
    classDef core fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef ext fill:#ffffc0,stroke:#333,stroke-width:1px
    classDef comm fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef util fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef cli fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef diag fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef log fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke-dasharray: 5 5
    classDef side fill:#f5f5f5,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
