# rickenator/rust_chain architecture

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

- Interactive diagram: https://gitdiagram.com/rickenator/rust_chain
- Repository: https://github.com/rickenator/rust_chain

## Overview

##### Main Components
- CLI/Entry Point: Represented by src/main.rs. This is where the application starts (including test execution).
- Blockchain Core: Represented by src/blockchain.rs. This module handles the core logic – block creation, chain management, and even loading/saving state (blockchain.json).
- Block Module: Represented by src/block.rs. This module defines how blocks are structured, created, and validated.
- Transaction Module: Represented by src/transaction.rs. It defines how transactions are structured and processed, and it interacts with the mempool logic.
- Merkle Proof Module: Represented by src/merkle_proof.rs. This is responsible for calculating and verifying Merkle proofs (a key security element in many blockchains).
- Utility Functions (if needed): Represented by src/utils.rs (for helper functions or common code).

##### Relationships and Interactions
- The CLI (main.rs) invokes the test routine (run_test() in main) and interacts with the blockchain core.
- The blockchain core (blockchain.rs) orchestrates the creation of blocks. It gathers transactions (from transaction.rs), processes them (and once the mempool reaches a threshold, a block is created), and calls upon the block module (block.rs) to build and validate a new block.
- When building a block, the blockchain core also uses the Merkle proof module (merkle_proof.rs) to compute the Merkle root and verify integrity.
- The persisted state (blockchain.json) is used when the blockchain goes out of scope and reloaded on subsequent runs.
- Optional: Utility functions might be used across these modules for common tasks such as formatting, logging, or file I/O.

##### Architectural Patterns and Design Principles
- Layered Design: The CLI acts as the presentation layer while the blockchain core and its domain objects (blocks, transactions, proofs) form the business logic layer.
- Separation of Concerns: Each source file does one well-defined task – block creation and validation, processing transactions, or computing Merkle proofs.
- Modular Design: Components are encapsulated in separate modules (Rust’s files), which promotes clarity and easier testing.

##### Relevant Technologies
- Rust and Cargo (for building/dependency management)
- The JSON file persistence for state saving and restoration
- Educational demonstration of blockchain concepts such as Proof of Work, mempool handling, and Merkle trees

## Diagram (Mermaid)

```mermaid
graph TD
    A["CLI (main.rs)"]:::presentation
    B["Blockchain Core (blockchain.rs)"]:::business
    C["Transaction Module (transaction.rs)"]:::business
    D["Block Module (block.rs)"]:::business
    E["Merkle Proof Module (merkle_proof.rs)"]:::business
    F["Utility Functions (utils.rs)"]:::business
    G["Persistent Storage (blockchain.json)"]:::external

    A -->|"invokes"| B
    B -->|"processes"| C
    B -->|"creates/validates"| D
    B -->|"computes/verifies"| E
    B <-->|"persists"| G

    B -..->|"uses"| F
    C -..->|"uses"| F
    D -..->|"uses"| F
    E -..->|"uses"| F

    click A "https://github.com/rickenator/rust_chain/blob/main/src/main.rs"
    click B "https://github.com/rickenator/rust_chain/blob/main/src/blockchain.rs"
    click C "https://github.com/rickenator/rust_chain/blob/main/src/transaction.rs"
    click D "https://github.com/rickenator/rust_chain/blob/main/src/block.rs"
    click E "https://github.com/rickenator/rust_chain/blob/main/src/merkle_proof.rs"
    click F "https://github.com/rickenator/rust_chain/blob/main/src/utils.rs"

    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef business fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;
```
