# blockstream/jade architecture

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

- Interactive diagram: https://gitdiagram.com/blockstream/jade
- Repository: https://github.com/blockstream/jade

## Overview

##### Main Components
- Bootloader Subsystem:
– Represented by the “bootloader_components” directory. It includes the bootloader support libraries, flash handling, secure boot, and various microcontroller-specific initialization code.
- Main Firmware Application:
– Contains the “main” directory with application initialization, UI, hardware interfacing (e.g., for display, camera, input, power management), cryptographic routines (e.g., attestation, RSA, AES, multisig support), network/serial communication, and firmware updating.
- Core Components & Libraries:
– The “components” folder contains supporting modules such as asset management, language autogeneration for localization, libraries like libwally-core, and hardware-specific interfacing (e.g., rotary encoder, esp32-quirc).
- Hardware Configuration:
– “configs” contains different sdkconfig defaults for various hardware platforms (e.g., display types and board revisions). Also, the “diy” folder holds documentation for DIY hardware adaptations.
- Emulation and Testing:
– The “main/qemu” directory and accompanying Dockerfiles (Dockerfile.qemu, docker-compose.yml) represent the virtualized/emulated environment. Also, there are test scripts (test_jade.py, various test_data) that verify firmware functionality.
- Client and API:
– The “jadepy” directory supplies a Python API/client to interact with the Jade device over serial, TCP, or via QEMU emulated interfaces.
- Build and Deployment:
– Multiple Dockerfiles, CMakeLists.txt files, and configuration/build scripts (including release scripts) support firmware building, deployment, and flashing operations.

##### Relationships and Interactions
- The Bootloader initializes hardware and then passes control to the main firmware.
- The Main Firmware, built with the esp-idf toolchain, uses various components to manage low-level hardware (display, BLE, input, camera) and higher-level functionalities (crypto, OTA, asset discovery).
- External interfaces:
- Serial ports, USB, BLE, and network interfaces enable communication and firmware updates.
- The Python client (jadepy) interacts with these interfaces for testing or remote control.
- Emulation Environment:
- QEMU containers (as defined in Dockerfile.qemu and docker-compose.yml) simulate hardware behavior, supporting CI and development.
- Build scripts ensure that configuration files (from “configs”) are copied appropriately before invoking idf.py commands.

##### Architectural Patterns and Design Principles
- Layered architecture: Separate bootloader from application firmware, with libraries and hardware abstraction layers in between.
- Modularity: Different hardware support modules and drivers (e.g., for different display or input types) are developed in separate directories.
- Expandability: Different configuration files and DIY hardware documentation indicate a design aimed at supporting multiple hardware revisions.
- Testing and Emulation: Multiple Docker environments and QEMU support indicate a strong emphasis on automated testing and reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Firmware Architecture
    subgraph "Firmware Architecture"
        Bootloader["Bootloader Subsystem"]:::boot
        MainFirmware["Main Firmware Application"]:::firmware
        CoreComponents["Core Components & Libraries"]:::lib
        Bootloader -->|"passes_control"| MainFirmware
        MainFirmware -->|"utilizes"| CoreComponents
    end

    %% Hardware Configuration & Interfaces
    subgraph "Hardware Configuration & Interfaces"
        HardwareConfig["Hardware Configuration"]:::config
        ExternalIF["External Interfaces<br/>(Serial,USB,BLE,Network)"]:::interface
        HardwareConfig -->|"configures"| MainFirmware
        MainFirmware -->|"communicates"| ExternalIF
    end

    %% Emulation, Testing, and Deployment
    subgraph "Emulation, Testing, and Deployment"
        Emulation["Emulation & Testing Environment"]:::emulation
        ClientAPI["Client & API Layer"]:::client
        BuildDeploy["Build & Deployment Tools"]:::build
    end

    BuildDeploy -->|"builds_bootloader"| Bootloader
    BuildDeploy -->|"builds_firmware"| MainFirmware
    Emulation -->|"tests"| MainFirmware
    ClientAPI -->|"interfaces_with"| ExternalIF

    %% Click Events for Component Mappings
    click Bootloader "https://github.com/blockstream/jade/tree/master/bootloader_components/"
    click MainFirmware "https://github.com/blockstream/jade/tree/master/main/"
    click CoreComponents "https://github.com/blockstream/jade/tree/master/components/"
    click HardwareConfig "https://github.com/blockstream/jade/tree/master/configs/"
    click HardwareConfig "https://github.com/blockstream/jade/tree/master/diy/"
    click Emulation "https://github.com/blockstream/jade/tree/master/main/qemu/"
    click Emulation "https://github.com/blockstream/jade/blob/master/Dockerfile.qemu"
    click Emulation "https://github.com/blockstream/jade/blob/master/docker-compose.yml"
    click Emulation "https://github.com/blockstream/jade/blob/master/test_jade.py"
    click ClientAPI "https://github.com/blockstream/jade/tree/master/jadepy/"
    click BuildDeploy "https://github.com/blockstream/jade/blob/master/CMakeLists.txt"
    click BuildDeploy "https://github.com/blockstream/jade/blob/master/Dockerfile.qemu"
    click BuildDeploy "https://github.com/blockstream/jade/tree/master/release/scripts/"

    %% Styles
    classDef boot fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef firmware fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef lib fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef config fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef interface fill:#ffccee,stroke:#cc0066,stroke-width:2px;
    classDef emulation fill:#e6e6e6,stroke:#666666,stroke-width:2px;
    classDef client fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef build fill:#d9ead3,stroke:#38761d,stroke-width:2px;
```
