# radicle-dev/heartwood architecture

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

- Interactive diagram: https://gitdiagram.com/radicle-dev/heartwood
- Repository: https://github.com/radicle-dev/heartwood

## Overview

##### Main system components
- Command-Line Interface: Represented by the radicle-cli crate. This is the user-facing component allowing for interactions with the Radicle network.
- Network Daemon: The radicle-node component that handles the decentralized networking, data storage, and node-specific functionalities.
- HTTP Daemon: The radicle-httpd that provides an HTTP API layer (and potentially additional UI elements) which leverages an underlying framework (Axum, indicated by files like axum_extra.rs).
- Supporting Libraries/Services: Several “radicle-” prefixed crates each serve a different purpose:
- radicle-cob for collaboration objects and change management.
- radicle-crdt for conflict-free replicated data types ensuring eventual consistency.
- radicle-crypto for cryptographic operations, particularly related to SSH.
- radicle-dag, radicle-fetch, and radicle-remote-helper for handling data fetching, git operations, and remote interactions.
- radicle-ssh for secure shell interactions.
- radicle-term for terminal UI and formatting output.
- radicle-tools to provide extra utility commands.
- Build & Deployment Tools: There are Dockerfiles, systemd service definitions, and various build scripts which indicate containerization and service management aspects.
- External Dependencies & Environment: The repository includes configurations for Docker, systemd, and potentially a seed node from which binaries are installed or synchronized.

##### Relationships and interactions
- The CLI (radicle-cli) acts as a front-end interface that interacts with radicle-node and other services by issuing commands which then trigger operations in the supporting crates.
- External services such as Docker deployments and systemd-managed services should be included to represent the production environment and operational glue.

##### Architectural patterns and design principles
- Modular Design: The project is divided into separate crates, clearly defining boundaries between the CLI, node, HTTP layer, and utility libraries. Represent each crate as a distinct module.
- Layered Architecture: There is a clear separation between the user interface (CLI/HTTP) and core network/data processing (radicle-node, radicle-cob, etc.). Mark this separation clearly.
- Distributed/Peer-to-Peer Communication: Emphasize the decentralized aspect by illustrating peer-to-peer links (gossip protocols) and data replication between nodes.
- Build & Deployment Automation: Indicate that the system is built using Rust’s Cargo, with additional deployment configurations using Docker, systemd, and scripts for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction Layer"
        CLI["radicle-cli\n(Command-Line Interface)"]:::ui
        HTTP["radicle-httpd\n(HTTP Daemon)"]:::ui
    end

    subgraph "Core Network Layer"
        NODE["radicle-node\n(Network Daemon)"]:::core
    end

    subgraph "Supporting Libraries"
        COB["radicle-cob\n(Collaboration Objects)"]:::lib
        CRDT["radicle-crdt\n(CRDT Library)"]:::lib
        CRYPTO["radicle-crypto\n(Cryptographic Ops)"]:::lib
        DAG["radicle-dag\n(DAG/Git Operations)"]:::lib
        FETCH["radicle-fetch\n(Data Fetching)"]:::lib
        REMOTE["radicle-remote-helper\n(Remote Git Helper)"]:::lib
        SSH["radicle-ssh\n(Secure Shell)"]:::lib
        TERM["radicle-term\n(Terminal UI)"]:::lib
        TOOLS["radicle-tools\n(Utility Tools)"]:::lib
    end

    subgraph "Deployment & Infrastructure"
        DOCKER["Docker Configurations"]:::deployment
        SYSTEMD["Systemd Services"]:::deployment
    end

    CLI -->|"issuesCommands"| NODE
    HTTP -->|"apiCalls"| NODE

    NODE -->|"collaboration"| COB
    NODE -->|"crdtOps"| CRDT
    NODE -->|"cryptoOps"| CRYPTO
    NODE -->|"dagProcessing"| DAG
    NODE -->|"dataFetching"| FETCH
    NODE -->|"remoteHelper"| REMOTE
    NODE -->|"sshCommunication"| SSH
    NODE -->|"terminalOutput"| TERM
    NODE -->|"utilityTools"| TOOLS

    DOCKER -->|"container"| HTTP
    DOCKER -->|"container"| NODE
    SYSTEMD -->|"serviceManagement"| HTTP
    SYSTEMD -->|"serviceManagement"| NODE

    click CLI "https://github.com/radicle-dev/heartwood/tree/master/radicle-cli/"
    click NODE "https://github.com/radicle-dev/heartwood/tree/master/radicle-node/"
    click HTTP "https://github.com/radicle-dev/heartwood/tree/master/radicle-httpd/"
    click COB "https://github.com/radicle-dev/heartwood/tree/master/radicle-cob/"
    click CRDT "https://github.com/radicle-dev/heartwood/tree/master/radicle-crdt/"
    click CRYPTO "https://github.com/radicle-dev/heartwood/tree/master/radicle-crypto/"
    click DAG "https://github.com/radicle-dev/heartwood/tree/master/radicle-dag/"
    click FETCH "https://github.com/radicle-dev/heartwood/tree/master/radicle-fetch/"
    click REMOTE "https://github.com/radicle-dev/heartwood/tree/master/radicle-remote-helper/"
    click SSH "https://github.com/radicle-dev/heartwood/tree/master/radicle-ssh/"
    click TERM "https://github.com/radicle-dev/heartwood/tree/master/radicle-term/"
    click TOOLS "https://github.com/radicle-dev/heartwood/tree/master/radicle-tools/"
    click DOCKER "https://github.com/radicle-dev/heartwood/tree/master/build/"
    click SYSTEMD "https://github.com/radicle-dev/heartwood/tree/master/systemd/"

    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef lib fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef deployment fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
