# ruitard/jsonsign architecture

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

- Interactive diagram: https://gitdiagram.com/ruitard/jsonsign
- Repository: https://github.com/ruitard/jsonsign

## Overview

##### Project Type & Purpose
- **Type**: A cross-platform C++ Command-Line Tool (CLI)
- **Purpose**: Sign and verify JSON files using RSA/ECDSA digital signatures, independent of JSON key ordering.

##### High-Level Components
A. **CLI Frontend**
- Source: `cli/json_sign.cpp`
- Uses: CLI11 for parsing commands (`generate-key-pair`, `sign`, `verify`).
B. **Core Library** (reusable modules in `src/`)
1. `keycore.hpp / .cpp`
- Key generation (RSA/ECDSA) interfaces
2. `pk.cpp`
- Sign & verify operations, wraps MbedTLS APIs
3. `base64.cpp`
- Encodes/decodes signatures to Base64 for embedding in JSON
4. `helper.hpp`
- JSON normalization (order-independent hashing) via nlohmann-json
C. **External Dependencies**
- **MbedTLS** (crypto primitives)
- **nlohmann-json** (JSON parsing/serialization)
- **CLI11** (command-line interface)
D. **Test Suite**
- Source: `test/`
- Validates end-to-end signing/verifying, uses sample `license.json`.
E. **Build System**
- CMake scripts (`CMakeLists.txt`, `cmake/`) orchestrate targets, find dependencies, and configure vcpkg toolchain.

##### Interactions & Data Flows
- **User → CLI Frontend**:
- User invokes `jsign sign` or `jsign verify`.
- CLI11 parses flags (`--key`, `--file`) and routes to the correct command handler.
- **CLI Frontend → Core Library**:
- Calls `generateKeyPair()`, `signJson()`, or `verifyJson()`.
- **Core Library ↔ MbedTLS**:
- `keycore` invokes RSA/ECDSA keygen, `pk` invokes sign/verify primitives.
- **Core Library ↔ nlohmann-json**:
- `helper` normalizes JSON (sorting, hashing), merges in signature field.
- **Core Library → base64**:
- Encodes raw signature bytes into the `"|signature|"` JSON field.
- **Core Library → File System**:
- Reads/writes JSON files and key files.
- **Test Suite → Core Library & CLI**:
- Executes commands in an isolated environment; asserts correct output.

##### Architectural Patterns & Principles
- **Modularity**: Clear separation between CLI layer and reusable signing library.
- **Dependency Injection**: Core library doesn’t know about CLI11; CLI imports only the public API.
- **Single Responsibility**: Each `.cpp/.hpp` in `src/` handles one concern (crypto, JSON, encoding).
- **Platform Abstraction**: CMake + vcpkg ensure cross-platform build consistency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "CLI Layer"
        User["User Terminal"]:::external
        CLI11Parser["CLI11 Parser"]:::extdep
        SignHandler["Command Handlers"]:::cli
    end

    subgraph "Core Library"
        CoreAPI["Core Library API"]:::core
        KeyCore["KeyCore Module"]:::core
        PK["Sign & Verify Module"]:::core
        Base64["Base64 Encoder"]:::core
        Helper["JSON Helper Module"]:::core
    end

    subgraph "External Dependencies"
        MbedTLS["MbedTLS"]:::extdep
        Nlohmann["nlohmann-json"]:::extdep
        CLI11Lib["CLI11"]:::extdep
    end

    subgraph "Filesystem & Storage"
        FS["Filesystem: JSON & Key Files"]:::storage
    end

    subgraph "Tests & Build"
        BuildRoot["Root CMake"]:::build
        CMakeSrc["src/CMakeLists.txt"]:::build
        CMakeCLI["cli/CMakeLists.txt"]:::build
        CMakeTest["test/CMakeLists.txt"]:::build
        TestSuite["Test Suite"]:::test
        Fixture["license.json"]:::storage
    end

    %% Data Flows and Dependencies
    User -->|"invokes jsign"| CLI11Parser
    CLI11Parser -->|"parses & routes"| SignHandler
    SignHandler -->|"calls"| CoreAPI

    CoreAPI -->|"generateKeyPair()"| KeyCore
    CoreAPI -->|"signJson()/verifyJson()"| PK
    CoreAPI -->|"encode()"| Base64
    CoreAPI -->|"normalizeJson()"| Helper
    CoreAPI -->|"read/write"| FS

    KeyCore -->|"RSA/ECDSA ops"| MbedTLS
    PK -->|"crypto primitives"| MbedTLS
    Helper -->|"JSON parsing"| Nlohmann

    TestSuite -->|"validates CLI & Core"| SignHandler
    TestSuite -->|"uses fixture"| Fixture

    BuildRoot --> CMakeSrc
    BuildRoot --> CMakeCLI
    BuildRoot --> CMakeTest

    %% Click Events
    click SignHandler "https://github.com/ruitard/jsonsign/blob/development/cli/json_sign.cpp"
    click CLI11Lib "https://github.com/ruitard/jsonsign/tree/development/cli/"
    click KeyCore "https://github.com/ruitard/jsonsign/blob/development/src/keycore.hpp"
    click PK "https://github.com/ruitard/jsonsign/blob/development/src/pk.cpp"
    click Base64 "https://github.com/ruitard/jsonsign/blob/development/src/base64.cpp"
    click Helper "https://github.com/ruitard/jsonsign/blob/development/src/helper.hpp"
    click MbedTLS "https://github.com/ruitard/jsonsign/blob/development/cmake/FindMbedTLS.cmake"
    click BuildRoot "https://github.com/ruitard/jsonsign/blob/development/CMakeLists.txt"
    click CMakeSrc "https://github.com/ruitard/jsonsign/blob/development/src/CMakeLists.txt"
    click CMakeCLI "https://github.com/ruitard/jsonsign/blob/development/cli/CMakeLists.txt"
    click CMakeTest "https://github.com/ruitard/jsonsign/blob/development/test/CMakeLists.txt"
    click TestSuite "https://github.com/ruitard/jsonsign/tree/development/test/"
    click Fixture "https://github.com/ruitard/jsonsign/blob/development/test/license.json"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E6FFEA,stroke:#22863A,color:#22863A;
    classDef extdep fill:#FFF5E6,stroke:#D47D05,color:#D47D05;
    classDef storage fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef build fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef test fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
