# minhvip08/zkshuffle architecture

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

- Interactive diagram: https://gitdiagram.com/minhvip08/zkshuffle
- Repository: https://github.com/minhvip08/zkshuffle

## Overview

##### Overall Structure and Main Components
- Project as a monorepo that leverages Yarn workspaces. Indicate that the repository is organized into distinct packages under “packages/”.
- Four main packages:
- @zk-shuffle/circuits – This contains the Circom circuits (e.g., babyjubjub, boolean, elgamal, matrix, permutation) along with unit tests. It is the foundation for generating zk proof artifacts (zkey, wasm, verifier contracts).
- @zk-shuffle/contracts – Contains Solidity smart contracts that incorporate the generated verifier contracts from the circuits package. It may also include additional functionalities and extensions as described in its documentation.
- @zk-shuffle/jssdk – A TypeScript SDK package that provides helper functions for generating zk proofs and cryptographic operations. This package is used by dApp developers to interact with the circuits and smart contracts.
- @zk-shuffle/proof – Provides utilities for generating zk proofs and is utilized by the contracts package for end-to-end testing.

##### Relationships and Interactions
- The contracts package depends on and imports the circuits artifacts (compiled circuits, verifiers).
- The jssdk and proof packages depend on the circuits package to perform proof generation and validation.
- The proof package also supports testing within the contracts package by offering proof generation utilities.
- Flow from circuit compilation: Circom circuits (from the circuits package) are compiled (outputting zkey/wasm/verifier contracts) and these outputs are integrated into the contracts package. Then the jssdk package provides a user-friendly interface to interact with these outputs in a dApp environment.

##### Architectural Patterns and Design Principles
- Modularity and clear separation of concerns. Each package encapsulates its functionality (circuits, contracts, SDK, proof utilities).
- That tests exist at various levels (unit tests in circuits, e2e tests in contracts, and specific tests for the proof package) to ensure quality and correct integration.
- Build and deployment scripts (e.g., Hardhat configurations in circuits and contracts, Yarn workspace commands) to indicate the CI/CD flows via GitHub workflows.

##### Relevant Technologies
- Circom for creating the ZKP circuits.
- Solidity and Hardhat for smart contract development and deployment.
- TypeScript for the jssdk and associated tooling in the proof package.
- Yarn v2 with workspaces for package management and project organization.
- Testing frameworks integrated into each package (unit testing, benchmark tests, etc.), as well as automated workflows defined in the .github/workflows directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    M["Monorepo (Yarn Workspaces)"]:::ci
    B["CI/CD (Yarn, Hardhat, GitHub Workflows)"]:::ci

    %% Circuits Package Subgraph
    subgraph "Circuits Package (@zk-shuffle/circuits)"
        C1["Circom circuits"]:::core
        C2["Build Scripts & Utils"]:::core
        C3["Unit Tests"]:::core
    end

    %% Contracts Package Subgraph
    subgraph "Contracts Package (@zk-shuffle/contracts)"
        CO1["Solidity Smart Contracts"]:::core
        CO2["Hardhat Configs & Deployment"]:::core
        CO3["Documentation"]:::core
    end

    %% JS SDK Package Subgraph
    subgraph "JS SDK Package (@zk-shuffle/jssdk)"
        J1["TypeScript SDK & Helpers"]:::sdk
    end

    %% Proof Package Subgraph
    subgraph "Proof Package (@zk-shuffle/proof)"
        P1["Proof Utilities"]:::proof
        P2["Tests"]:::proof
    end

    %% Monorepo connections to packages and CI/CD
    M -->|"contains"| C1
    M -->|"contains"| CO1
    M -->|"contains"| J1
    M -->|"contains"| P1
    M -->|"triggers"| B

    %% Dependencies and Data Flow
    C1 -->|"compiled_output"| CO1
    C1 -->|"artifacts"| J1
    C1 -->|"used_for_proofs"| P1
    CO1 -->|"test_integration"| P1
    CO1 -->|"interfaces"| J1

    %% Click Events for Circuits Package
    click C1 "https://github.com/minhvip08/zkshuffle/tree/main/packages/circuits/circuits"
    click C2 "https://github.com/minhvip08/zkshuffle/tree/main/packages/circuits/utils"
    click C3 "https://github.com/minhvip08/zkshuffle/tree/main/packages/circuits/tests"

    %% Click Events for Contracts Package
    click CO1 "https://github.com/minhvip08/zkshuffle/tree/main/packages/contracts/contracts"
    click CO2 "https://github.com/minhvip08/zkshuffle/blob/main/packages/contracts/hardhat.config.ts"
    click CO3 "https://github.com/minhvip08/zkshuffle/tree/main/packages/contracts/docs"

    %% Click Event for JS SDK Package
    click J1 "https://github.com/minhvip08/zkshuffle/tree/main/packages/jssdk/src"

    %% Click Events for Proof Package
    click P1 "https://github.com/minhvip08/zkshuffle/tree/main/packages/proof/src"
    click P2 "https://github.com/minhvip08/zkshuffle/tree/main/packages/proof/tests"

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef sdk fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef proof fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef ci fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
