# nrfcloud/utils architecture

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

- Interactive diagram: https://gitdiagram.com/nrfcloud/utils
- Repository: https://github.com/nrfcloud/utils

## Overview

##### Main Components
- nRF Cloud Utils CLI/Application: Representing the top-level command interface where users execute commands like creating a CA, installing device credentials, and performing onboarding.
- Core Script Modules (inside the nrfcloud_utils package): Break these out into several functional areas:
- Certificate Authority (CA) Management (e.g., create_ca_cert.py)
- Device Credential Generation (e.g., create_device_credentials.py and device_credentials_installer.py)
- Onboarding/Provisioning (e.g., nrf_cloud_onboard.py, nrf_cloud_diap.py)
- Utility/Helper Modules (e.g., cli_helpers.py, command_interface.py, modem_credentials_parser.py)
- External Interactions:
- nRF Cloud REST API: The external nRF Cloud services accessed for device registration and on-boarding.
- End-user Device Firmware: While not directly part of the code base, the utilities assume interaction with devices running specific firmware (AT Host library or AT Client sample), which should be noted.

##### Relationships and Interactions
- The CLI serves as the entry point that then calls various functions within the core modules.
- The modules related to certificate management and device credentials form a workflow: first create a CA certificate, then generate device-specific certificates with the utility module.
- Device on-boarding scripts use the generated certificates and communicate with the nRF Cloud REST API using the provided API key for registration.
- There is a clear data flow from certificate creation → device credentials installation → cloud device onboarding.
- Unit tests (in the tests directory) are designed to verify these functions; include them on the side as a testing/validation component.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The code is divided into modules each responsible for a specific functionality (e.g., certificate creation is handled separately from device onboarding).
- CLI-driven Workflow: The design supports a command-line interface that orchestrates the flow from certificate generation to cloud registration.
- Modular Interaction with External APIs: The nRF Cloud API is abstracted within specific modules, ensuring that REST calls and responses are encapsulated within dedicated components.
- Testable Design: With unit tests corresponding to major components (e.g., test_create_ca_cert.py), the architecture encourages modular and isolated testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI/Command Interface"
        CI["Command Interface"]:::cli
        CH["CLI Helpers"]:::cli
    end

    subgraph "Certificate Authority & Credential Management"
        CA["CA Management"]:::ca
    end

    subgraph "Device Credential Generation"
        DC["Create Device Credentials"]:::cred
        DI["Device Credentials Installer"]:::cred
    end

    subgraph "nRF Cloud API Integration"
        ON["nRF Cloud Onboard"]:::api
        DIAP["nRF Cloud DIAP"]:::api
        DM["nRF Cloud Device Mgmt"]:::api
    end

    subgraph "Utility Helpers"
        MP["Modem Credentials Parser"]:::util
        GA["Gather Attestation Tokens"]:::util
        PJ["Create Proxy JWT"]:::util
        NB["Nordic Boards"]:::util
        RT["RTT Interface"]:::util
    end

    subgraph "Testing Framework"
        TCA["test_create_ca_cert"]:::test
        TDC["test_create_device_credentials"]:::test
        TMP["test_modem_credentials_parser"]:::test
    end

    ext_api["nRF Cloud REST API"]:::external
    ext_fw["End-user Device Firmware"]:::external

    CI -->|"executes"| CA
    CH -->|"executes"| CA

    CA -->|"generates_cert"| DC
    DC -->|"installs_creds"| DI
    DI -->|"triggers_onboard"| ON

    ON -->|"api_call"| ext_api
    DIAP -->|"data_exchange"| ext_api
    DM -->|"data_exchange"| ext_api

    CI -->|"calls"| MP
    CH -->|"calls"| MP

    ON ---|"depends_on"| ext_fw

    CA --- TCA
    DC --- TDC
    MP --- TMP

    click CI "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/command_interface.py"
    click CH "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/cli_helpers.py"
    click CA "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/create_ca_cert.py"
    click DC "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/create_device_credentials.py"
    click DI "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/device_credentials_installer.py"
    click ON "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/nrf_cloud_onboard.py"
    click DIAP "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/nrf_cloud_diap.py"
    click DM "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/nrf_cloud_device_mgmt.py"
    click MP "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/modem_credentials_parser.py"
    click GA "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/gather_attestation_tokens.py"
    click PJ "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/create_proxy_jwt.py"
    click NB "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/nordic_boards.py"
    click RT "https://github.com/nrfcloud/utils/blob/main/src/nrfcloud_utils/rtt_interface.py"
    click TCA "https://github.com/nrfcloud/utils/blob/main/tests/test_create_ca_cert.py"
    click TDC "https://github.com/nrfcloud/utils/blob/main/tests/test_create_device_credentials.py"
    click TMP "https://github.com/nrfcloud/utils/blob/main/tests/test_modem_credentials_parser.py"

    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef ca fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef cred fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef api fill:#A3E4D7,stroke:#117864,stroke-width:2px;
    classDef util fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef test fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
