# worldfnd/provekit architecture

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

- Interactive diagram: https://gitdiagram.com/worldfnd/provekit
- Repository: https://github.com/worldfnd/provekit

## Overview

##### Main Components
- Zero-Knowledge Circuit Management:
- Noir circuits found under the “noir-examples” directories (e.g., basic, poseidon-rounds, etc.). These represent the input specifications that must be compiled.
- Circuit Compilation & Preparation:
- “noir-r1cs” component, which contains the logic for converting Noir circuits into R1CS representations. Under this umbrella, emphasize the sub-modules and binary commands (e.g., “prepare”, “prove”, “cmd/prepare.rs”, “cmd/prove.rs”) that handle proof setup and proof generation.
- Hashing and Auxiliary Benchmarks:
- “merkle-hash-bench” directory as a component that benchmarks various hash algorithms (like Blake3, Keccak, Poseidon variations, etc.). This is key to understanding the performance aspects of the toolkit.
- External Dependencies and Libraries:
- FRI / Advanced Mathematical Modules:
- “sage/fri-and-friends” folder which contains notebooks, Python scripts, and documentation around FRI (Fast Reed-Solomon Interactive Oracle Proofs of Proximity) concepts. This component is essential if FRI-based zero-knowledge proofs are part of the proof scheme.
- Supporting Scripts and CI/CD:
- “.github/workflows” (CI configurations) and “scripts” directories that automate testing and execution flows. Though not core to the ZKP functionality, they form part of the overall system ecosystem.

##### Relationships and Data Flow
- Next, illustrate the compilation stage: the Noir compiler (external tool as noted in the README) converts circuits into a JSON artifact.
- Link these processes to the external dependency modules (like gnark-whir) that use these proofs for verification purposes.
- On a side branch, illustrate the FRI and related interactive proofs generation and validation from the Sage notebooks.
- Finally, include flow control elements that represent automation (triggered by GitHub workflows or scripts) that run tests or end-to-end demo tasks.

##### Architectural Patterns and Design Principles
- Modular separation: The project is clearly segmented – circuit definition (noir-examples), compilation/proof generation (noir-r1cs), and auxiliary tools (merkle-hash-bench, sage). Stress the importance of keeping these responsibilities separate.
- Pipeline Data Flow: Consider using a pipeline-like layout that reflects the sequential transformation from circuit source → compiled artifact → proof preparation → proof generation → verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Circuit Input & Definition"
        NC["Noir Circuit Examples"]:::inHouse
    end

    subgraph "Compilation Pipeline"
        NC -->|"Noir_Compiler_(External)"| CJ["Compiled JSON Artifact"]:::process
        subgraph "Noir R1CS Compiler & Prover"
            PRE["Prepare Command"]:::inHouse
            PVE["Prove Command"]:::inHouse
            PRE -->|"to_generate"| PVE
        end
        CJ -->|"Prepare"| PRE
        PVE -->|"Proof_Artifact"| PRF["Proof Artifact"]:::process
    end

    subgraph "External Verification & Dependencies"
        PRF -->|"Verification"| EXV["Verification_(gnark-whir)"]:::external
        EXV --> DEP["External Dependencies"]:::external
        DEP ---|"dependson"| E1["WHIR"]:::external
        DEP ---|"dependson"| E2["Spongefish"]:::external
        DEP ---|"dependson"| E3["gnark-skyscraper"]:::external
        DEP ---|"dependson"| E4["gnark-nimue"]:::external
        DEP ---|"dependson"| E5["gnark-whir"]:::external
        DEP ---|"dependson"| E6["noir"]:::external
    end

    subgraph "Auxiliary Modules & Automation"
        HR["Merkle Hash Bench"]:::inHouse
        HR -->|"contains"| HB["Hash Functions"]:::inHouse
        FRI["FRI Module (Sage Notebooks)"]:::inHouse
        WF["GitHub Workflows"]:::automation
        SC["Scripts"]:::automation
    end

    subgraph "Mobile Targeting"
        MC["Mobile Client"]:::client
    end

    %% Additional connections
    PVE -->|"triggers"| HR
    PRE -->|"utilizes"| FRI
    WF -->|"automates"| CJ
    SC -->|"automates"| CJ
    PRF -->|"consumed_by"| MC

    %% Click Events
    click NC "https://github.com/worldfnd/provekit/tree/main/noir-examples/"
    click PRE "https://github.com/worldfnd/provekit/blob/main/noir-r1cs/src/bin/cmd/prepare.rs"
    click PVE "https://github.com/worldfnd/provekit/blob/main/noir-r1cs/src/bin/cmd/prove.rs"
    click HR "https://github.com/worldfnd/provekit/tree/main/merkle-hash-bench/"
    click HB "https://github.com/worldfnd/provekit/tree/main/merkle-hash-bench/src/hashes/"
    click FRI "https://github.com/worldfnd/provekit/tree/main/sage/fri-and-friends/"
    click WF "https://github.com/worldfnd/provekit/tree/main/.github/workflows/"
    click SC "https://github.com/worldfnd/provekit/tree/main/scripts/"

    %% Styles
    classDef inHouse fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef process fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef automation fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef client fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
