# simoneroznowicz/master-thesis architecture

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

- Interactive diagram: https://gitdiagram.com/simoneroznowicz/master-thesis
- Repository: https://github.com/simoneroznowicz/master-thesis

## Overview

##### Project type and purpose (what you’re diagramming)
This is a **single-machine, end-to-end Rust implementation** of the **PoEUS (Proof of Efficiently Usable Space) protocol**. Even though everything runs as one process (`cargo run --release -- <loglevel>`), the codebase clearly models **distinct protocol roles and phases** (e.g., prover/verifier/client-like communication) and a **data pipeline** (input file → block generation/encoding → commitments/Merkle structures → proof generation → verification).

##### File structure analysis (what the architecture wants to be)
Top-level:
- `PoEUS/CPoS/Cargo.toml` → one Rust crate (likely one binary)
- `PoEUS/CPoS/src/main.rs` → entrypoint / orchestrator
- `PoEUS/CPoS/src/block_generation/*` → encoding/decoding pipeline, block creation, utilities
- `PoEUS/CPoS/src/Merkle_Tree/*` → Merkle tree structures and verification
- `PoEUS/CPoS/src/PoS/*` → proof generation and verification logic (prover/verifier roles)
- `PoEUS/CPoS/src/communication/*` → message/path generation, client abstraction, protocol structs
- `input.mp4`, `output.bin` → sample workload artifacts (filesystem IO is part of the real system)

This strongly suggests an internal architecture of:
**Orchestrator → Block Generation → Commitment (Merkle) → Challenge/Path selection → Prover → Verifier**
with “communication” acting as the glue for “who sends what to whom”, even if it’s in-memory.

##### README insights (what to emphasize)
- It is a **complete end-to-end** protocol implementation, not just a library.
- It’s sensitive to **performance/parallelization** in *block generation* (important to annotate concurrency/CPU-heavy stage).
- Operates on **large input files** (GB-scale), so the **data plane** (file → blocks → encoded artifacts) matters.

##### CLI / Entrypoint
- `src/main.rs`
- Responsibility: parse log level, run protocol end-to-end, coordinate phases.

##### Block Generation Subsystem
- `src/block_generation/main.rs`, `blockgen.rs`, `encoder.rs`, `decoder.rs`, `utils.rs`
- Responsibility: read `input.mp4`, split into blocks, encode blocks, possibly decode for checks, produce on-disk/in-memory representations (e.g., `output.bin`).

##### Merkle Tree / Commitment Subsystem
- `src/Merkle_Tree/mod.rs`, `structs.rs`, `client_verify.rs`
- Responsibility: build Merkle tree over block commitments (or encoded blocks), provide root commitment, provide/verify Merkle proofs (paths).

##### Proof-of-Space / Protocol Logic
- `src/PoS/prover.rs`, `verifier.rs`, `utils.rs`, `mod.rs`
- Responsibility: implement PoEUS proving and verification steps; “Prover” generates responses; “Verifier” checks them.

##### Communication / Message & Path Orchestration
- `src/communication/client.rs`, `path_generator.rs`, `structs.rs`, `mod.rs`
- Responsibility: define protocol messages/structs, generate challenge paths / queries, emulate client/verifier interactions.

##### External Dependencies (explicitly show them even if not in tree)
- **Filesystem** (reads `input.mp4`, writes `output.bin`)
- **CPU / Parallel execution** (block generation parallelization)

##### Architectural patterns / principles

- **Pipeline architecture**: block generation → commitment → challenge/prove → verify
- **Role separation** (even in-process): Prover vs Verifier vs Client/Coordinator
- **Deterministic data structure verification**: Merkle proofs enable verification without full data
- **Performance hotspot**: block generation is parallelizable; annotate it with “parallel / CPU-bound”

##### Relevant technologies
- **Rust binary crate** (single executable)
- **Merkle Tree** (commitment + membership proofs)
- **Proof protocol modules**: `prover.rs` / `verifier.rs`

##### C4 Level 1 (Context)
- Actor: “User (runs cargo)”
- System: “PoEUS Protocol Runner (CPoS)”
- External: Filesystem (input/output)

##### C4 Level 2 (Container) (even if everything is one binary, treat modules as containers)
- CLI/Orchestrator
- Block Generation
- Commitment (Merkle)
- PoS Prover
- PoS Verifier
- Communication/Path Generator
- Filesystem

##### C4 Level 3 (Component) (map directly to directories/files)
- Block Generation: encoder/decoder/blockgen
- PoS: prover/verifier/utils
- Merkle: structs/client_verify
- Communication: client/path_generator/structs

Runtime ordering:
- main → block_generation(main/blockgen/encoder)
- build Merkle root
- path_generator produces challenges
- prover constructs proof (+ Merkle paths)
- verifier validates (possibly via client_verify)
- return result

This combo removes confusion about “is it distributed?” while still accurately representing the protocol roles.

##### Diagramming rules to follow (make it unambiguous)
Elements explicitly:

- **Clear labels**
- **bulk data** (thick line) vs **proof/messages** (thin line)
- Example scheme:
- Blue rectangles: internal Rust modules
- Orange hexagon: cryptographic primitive (hash)
- Green rounded rectangles: protocol roles (Prover/Verifier)
- **Annotate trust boundaries**
- Even on one machine, mark conceptual boundaries:
- “Prover side” vs “Verifier side”
- This is crucial for protocol comprehension.

##### Concrete “best” component breakdown for *this repo* (don’t overthink—split aggressively)

- `main.rs` (Orchestrator)
- `block_generation::main`
- `block_generation::blockgen`
- `block_generation::encoder`
- `block_generation::decoder`
- `block_generation::utils`
- `Merkle_Tree::structs`
- `Merkle_Tree::client_verify`
- `PoS::prover`
- `PoS::verifier`
- `PoS::utils`
- `communication::client`
- `communication::path_generator`
- `communication::structs`
- External: Filesystem input/output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context / System Boundary
    %% =========================
    User["User"]:::actor

    subgraph "Single-machine PoEUS Runner (Rust binary crate: CPoS)"
        Crate["Rust Crate (single executable)"]:::crate
        Main["CLI / Entrypoint / Orchestrator (main.rs)"]:::orchestrator

        subgraph "Data Pipeline (bulk data plane)"
            subgraph "Block Generation Subsystem (block_generation)"
                BGMod["Module wiring (mod.rs)"]:::wiring
                BGMain["Pipeline driver (main.rs)"]:::module
                Blockgen["Block splitting / creation (blockgen.rs)"]:::module
                Encoder["Block encoder (encoder.rs)"]:::module
                Decoder["Block decoder (decoder.rs)"]:::module
                BGUtils["Utilities (utils.rs)"]:::module
                ParallelNote["Parallel / CPU-bound stage"]:::note
            end

            subgraph "Commitment Subsystem (Merkle_Tree)"
                MTMod["Module wiring (mod.rs)"]:::wiring
                MTStructs["Merkle data structures (structs.rs)"]:::module
                ClientVerify["Merkle proof verification (client_verify.rs)"]:::module
                MerkleRoot["Merkle root commitment"]:::artifact
            end
        end

        subgraph "Protocol Control Plane (messages / proofs)"
            subgraph "Communication / Orchestration (communication)"
                CommMod["Module wiring (mod.rs)"]:::wiring
                Client["Client abstraction (client.rs)"]:::role
                PathGen["Challenge / path generator (path_generator.rs)"]:::module
                CommStructs["Protocol message structs (structs.rs)"]:::module
            end

            subgraph "PoEUS Protocol Logic (PoS)"
                PoSMod["Module wiring (mod.rs)"]:::wiring
                Prover["Prover role (prover.rs)"]:::role
                Verifier["Verifier role (verifier.rs)"]:::role
                PoSUtils["PoS utilities (utils.rs)"]:::module
            end

            HashFn["Hash function (e.g., SHA-256/Blake3)"]:::crypto
            Entropy["Challenge entropy source"]:::external
        end
    end

    subgraph "Filesystem (external)"
        InputFile[("input.mp4")]:::storage
        OutputFile[("output.bin")]:::storage
    end

    %% =========================
    %% High-level flow (vertical)
    %% =========================
    User -->|"runs cargo run --release"| Main

    Crate --> Main

    %% Orchestration calls into subsystems
    Main -->|"coordinates run"| BGMain
    Main -->|"coordinates run"| PathGen
    Main -->|"collects result"| Verifier

    %% =========================
    %% Data plane (bulk)
    %% =========================
    InputFile ==>|"bulk data: read file"| BGMain
    BGMain -->|"calls"| BGMod
    BGMain -->|"splits"| Blockgen
    Blockgen -->|"uses"| BGUtils
    Blockgen -->|"produces blocks"| Encoder
    Encoder -->|"optional check"| Decoder
    Encoder ==>|"bulk data: writes encoded output"| OutputFile

    %% Merkle commitment build
    Encoder -->|"encoded blocks / commitments"| MTStructs
    MTStructs -->|"builds"| MerkleRoot
    MTStructs -->|"wired via"| MTMod

    %% Performance annotation
    BGMain -->|"CPU-bound"| ParallelNote
    ParallelNote -.->|"parallelizable operations"| Encoder

    %% Hash usage
    MTStructs -->|"hashes"| HashFn
    Prover -->|"hashes"| HashFn
    Verifier -->|"hashes"| HashFn

    %% =========================
    %% Control plane (messages/proofs)
    %% =========================
    Entropy -->|"seed / randomness"| PathGen
    PathGen -->|"uses"| CommStructs
    Client -->|"uses"| CommStructs
    CommMod -->|"wires"| Client
    CommMod -->|"wires"| PathGen
    CommMod -->|"wires"| CommStructs

    %% Challenge -> Prover
    PathGen -->|"challenge: selected indices / paths"| Prover

    %% Prover needs Merkle auth paths from commitment
    Prover -->|"requests auth paths"| MTStructs
    MTStructs -->|"returns Merkle auth path(s)"| Prover

    %% Prover -> Verifier proof response
    Prover -->|"proof response + auth path(s)"| Verifier

    %% Verifier checks Merkle proofs + root
    Verifier -->|"verifies membership"| ClientVerify
    ClientVerify -->|"uses root"| MerkleRoot
    ClientVerify -->|"uses structs"| MTStructs

    %% Result back to orchestrator
    Verifier -->|"accept / reject"| Main

    %% PoS internal wiring
    PoSMod -->|"wires"| Prover
    PoSMod -->|"wires"| Verifier
    PoSMod -->|"wires"| PoSUtils
    Prover -->|"uses"| PoSUtils
    Verifier -->|"uses"| PoSUtils

    %% =========================
    %% Click events (mapped paths)
    %% =========================
    click Crate "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/Cargo.toml"
    click Main "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/main.rs"

    click BGMod "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/mod.rs"
    click BGMain "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/main.rs"
    click Blockgen "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/blockgen.rs"
    click Encoder "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/encoder.rs"
    click Decoder "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/decoder.rs"
    click BGUtils "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/block_generation/utils.rs"

    click MTMod "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/Merkle_Tree/mod.rs"
    click MTStructs "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/Merkle_Tree/structs.rs"
    click ClientVerify "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/Merkle_Tree/client_verify.rs"

    click PoSMod "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/PoS/mod.rs"
    click Prover "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/PoS/prover.rs"
    click Verifier "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/PoS/verifier.rs"
    click PoSUtils "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/PoS/utils.rs"

    click CommMod "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/communication/mod.rs"
    click Client "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/communication/client.rs"
    click PathGen "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/communication/path_generator.rs"
    click CommStructs "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/src/communication/structs.rs"

    click InputFile "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/input.mp4"
    click OutputFile "https://github.com/simoneroznowicz/master-thesis/blob/master/PoEUS/CPoS/output.bin"

    %% =========================
    %% Styles (color + shapes)
    %% =========================
    classDef actor fill:#111827,stroke:#0b1220,color:#ffffff,stroke-width:2px
    classDef crate fill:#0f172a,stroke:#38bdf8,color:#e2e8f0,stroke-width:2px
    classDef orchestrator fill:#1d4ed8,stroke:#93c5fd,color:#ffffff,stroke-width:2px
    classDef module fill:#2563eb,stroke:#bfdbfe,color:#ffffff,stroke-width:1.5px
    classDef wiring fill:#1e40af,stroke:#bfdbfe,color:#ffffff,stroke-width:1.5px,stroke-dasharray: 4 3
    classDef role fill:#16a34a,stroke:#bbf7d0,color:#052e16,stroke-width:2px
    classDef storage fill:#6b7280,stroke:#e5e7eb,color:#111827,stroke-width:2px
    classDef crypto fill:#f59e0b,stroke:#fde68a,color:#111827,stroke-width:2px
    classDef external fill:#374151,stroke:#d1d5db,color:#ffffff,stroke-width:1.5px
    classDef note fill:#0ea5e9,stroke:#bae6fd,color:#0b1220,stroke-width:1.5px,stroke-dasharray: 6 4
    classDef artifact fill:#334155,stroke:#cbd5e1,color:#f8fafc,stroke-width:1.5px
```
