# sbabic/swupdate architecture

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

- Interactive diagram: https://gitdiagram.com/sbabic/swupdate
- Repository: https://github.com/sbabic/swupdate

## Overview

##### Project type and purpose
- This is SWUpdate, an open-source C framework and agent for performing safe, atomic software updates on embedded Linux devices. It ships as a daemon/CLI (`swupdate`), a library, a built-in web server, language bindings, and example front-ends.

##### File structure
- Top-level key folders:
- core: the main update engine, parser, state machine, threads, notifier
- corelib: low-level interfaces (downloaders, channel/CMS, cryptographic verification)
- handlers: modules that perform actual installation steps (flash, partitioning, delta, Docker, shell scripts, custom Lua handlers)
- bootloader: bootloader integration back ends (U-Boot, GRUB, none, etc.)
- fs: filesystem drivers and mke2fs tooling
- parser: sw-description parsing front‐end
- mongoose: embedded HTTP server for local GUI/API
- ipc: local IPC channels (progress, network)
- bindings: language wrappers (Lua, NodeJS)
- web-app: JS/CSS/HTML front end that can talk to the embedded server or remote instance
- tools: CLI client, progress reporter, IPC client, Python wrapper
- suricatta: example integration with Suricatta bus for broadcast updates
- Build files: Makefile/Kconfig everywhere → highly configurable via build system, Yocto/Buildroot integration, optional modules, conditional compilation.
- CI, scripts, tests and examples accompany each major area.

##### README for additional insights
- Confirms it’s an embedded update agent supporting local storage, integrated REST server, REST client to HawkBit, OTA downloads, customizable handlers, scripting via Lua, cryptographic verification (OpenSSL, mbedTLS, WolfSSL), multiple update strategies (full, delta), fail‐safe atomic updates.
- Mentions integration points: library API, IPC progress interface, web UI, external services (hawkBit).

##### Be detailed
- How the testing and CI scripts fit (e.g., test harness invoking APIs or handlers).
- Don’t hesitate to display many small components—this modularity is a core architectural strength.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Parsing & Core Engine
    subgraph "Parsing & Core Engine"
        direction TB
        Parser["Parser Front-end"]:::core
        CoreEngine["Swupdate Core Engine"]:::core
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        CoreLib["Core Libraries (download, crypto, CMS)"]:::lib
    end

    %% Handler Modules
    subgraph "Handler Modules"
        direction TB
        FSHandler["Filesystem Handler"]:::handler
        FlashHandler["Flash Handler"]:::handler
        DeltaHandler["Delta Handler"]:::handler
        DockerHandler["Docker Handler"]:::handler
        LuaHandler["Lua Handler"]:::handler
        ScriptHandler["Script Handler"]:::handler
    end

    %% Bootloader Modules
    subgraph "Bootloader Modules"
        direction TB
        Bootloader["Bootloader Modules"]:::handler
    end

    %% Filesystem Drivers & Tools
    subgraph "Filesystem Drivers & Tools"
        direction TB
        FSDrivers["Filesystem Drivers & Tools"]:::handler
    end

    %% Networking & IPC
    subgraph "Networking & IPC"
        direction TB
        Network["Network Interface & Threads"]:::net
        IPC["IPC Interfaces"]:::net
    end

    %% Embedded HTTP Server
    subgraph "Embedded HTTP Server"
        direction TB
        Mongoose["Mongoose HTTP Server"]:::net
    end

    %% Language Bindings
    subgraph "Language Bindings"
        direction TB
        LuaBind["Lua Binding"]:::ext
        NodeBind["NodeJS Binding"]:::ext
    end

    %% Web UI & Tools
    subgraph "Web UI & Tools"
        direction TB
        WebUI["Web UI Front-end"]:::ext
        Tools["CLI Tools & Python"]:::ext
    end

    %% Examples
    subgraph "Examples"
        direction TB
        Suricatta["Suricatta Integration"]:::ext
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Hawkbit["HawkBit/OTA Server"]:::external
        LocalStorage["Local Storage (USB/SD)"]:::external
    end

    %% Relationships
    Tools -->|"invokes"| CoreEngine
    Parser -->|"parses descriptions"| CoreEngine
    CoreEngine -->|"uses"| CoreLib
    CoreLib -->|"download/decrypt"| Network
    CoreEngine -->|"dispatches to"| FSHandler
    CoreEngine -->|"dispatches to"| FlashHandler
    CoreEngine -->|"dispatches to"| DeltaHandler
    CoreEngine -->|"dispatches to"| DockerHandler
    CoreEngine -->|"dispatches to"| LuaHandler
    CoreEngine -->|"dispatches to"| ScriptHandler
    CoreEngine -->|"updates via"| Bootloader
    FSHandler -->|"writes on"| FSDrivers
    FlashHandler -->|"writes on"| FSDrivers
    Bootloader -->|"manages boot partitions"| FSDrivers
    CoreEngine -->|"emits progress"| IPC
    IPC -->|"progress events"| Tools
    IPC -->|"progress events"| WebUI
    WebUI -->|"REST API calls"| Mongoose
    Mongoose -->|"forwards requests"| CoreEngine
    NodeBind -->|"calls API"| CoreEngine
    LuaBind -->|"scripting API"| CoreEngine
    Network -->|"fetch updates"| Hawkbit
    Network -->|"fetch updates"| LocalStorage
    Suricatta -->|"example uses"| CoreEngine

    %% Click Events
    click Parser "https://github.com/sbabic/swupdate/tree/master/parser/"
    click CoreEngine "https://github.com/sbabic/swupdate/tree/master/core/"
    click CoreLib "https://github.com/sbabic/swupdate/tree/master/corelib/"
    click FSHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click FlashHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click DeltaHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click DockerHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click LuaHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click ScriptHandler "https://github.com/sbabic/swupdate/tree/master/handlers/"
    click Bootloader "https://github.com/sbabic/swupdate/tree/master/bootloader/"
    click FSDrivers "https://github.com/sbabic/swupdate/tree/master/fs/"
    click Network "https://github.com/sbabic/swupdate/blob/master/core/network_thread.c"
    click IPC "https://github.com/sbabic/swupdate/tree/master/ipc/"
    click Mongoose "https://github.com/sbabic/swupdate/tree/master/mongoose/"
    click LuaBind "https://github.com/sbabic/swupdate/blob/master/bindings/lua_swupdate.c"
    click NodeBind "https://github.com/sbabic/swupdate/tree/master/bindings/nodejs/"
    click WebUI "https://github.com/sbabic/swupdate/tree/master/web-app/"
    click Tools "https://github.com/sbabic/swupdate/tree/master/tools/"
    click Suricatta "https://github.com/sbabic/swupdate/tree/master/suricatta/"

    %% Styles
    classDef core fill:#AED3F7,stroke:#036
    classDef lib fill:#C3F7AE,stroke:#063
    classDef handler fill:#F7E6AE,stroke:#863
    classDef net fill:#F7AEAE,stroke:#630
    classDef ext fill:#DCDCDC,stroke:#888
    classDef external fill:#FFF,stroke-dasharray: 5 5,stroke:#000
```
