# google/longfellow-zk architecture

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

- Interactive diagram: https://gitdiagram.com/google/longfellow-zk
- Repository: https://github.com/google/longfellow-zk

## Overview

Step 1: Identify Project Type and Purpose
- This is a C++ “monorepo” library (Longfellow ZK) for building zero-knowledge proofs over legacy identity formats (MDOC, JWT, W3 VC).
- It exposes core building blocks (finite fields, FFTs, merkle trees, sumcheck, circuits, provers, verifiers) and is consumed by CMake clients.
- It includes unit tests and benchmarks (googletest, googlebenchmark).

Step 2: Analyze File Structure
- Top-level:
- .devcontainer, .github/workflows: CI and dev container config
- lib/: all C++ submodules with CMake build files
- docs/: Doxygen API reference
- README.md, LICENSE, Doxyfile
- Under lib/, key subdirectories (each with its own CMakeLists.txt):
- util: basic utilities (logging, serialization, crypto wrappers)
- algebra: finite‐field, FFT, convolution, Reed-Solomon, etc.
- arrays, cbor: data structures and parsers
- circuits: Zero-knowledge circuit definitions (anoncred, base64, cbor_parser, compiler, ecdsa, jwt, logic, mac, mdoc, sha, sha3)
- ec, gf2k: elliptic-curve and GF(2^k) support
- merkle: merkle tree commitments
- proto: circuit protobuf messages
- random: randomness engines/transcripts
- sumcheck: sumcheck protocol layers
- zk: top-level zk_prover, zk_verifier, zk_common
- testing: test runner and harness

Step 3: README Insights
- Describes overall goal: zero-knowledge over legacy credentials
- Points out external dependencies: openssl, zstd, clang, googletest, googlebenchmark
- No external network or runtime services—pure C++ library

a. Build & Dev Environment
- CMake (lib/CMake, scripts)
- Devcontainer / Docker
- CI pipelines (.github/workflows)
- External deps: OpenSSL, Zstd, googletest, googlebenchmark
1. util
2. algebra, arrays, cbor, ec, gf2k, merkle, random
3. circuits (sub‐packages)
4. sumcheck
5. zk (zk_common, zk_prover, zk_verifier)
c. Tests & Benchmarks
- Unit tests (googletest)
- Benchmarks (googlebenchmark)
d. Docs
- Doxygen output under docs/html

- util → algebra, arrays, cbor, random
- algebra → circuits & sumcheck
- cbor, ec, gf2k, merkle → circuits
- circuits (compiler backend) → sumcheck & zk layers
- sumcheck → zk_prover & zk_verifier
- zk_prover/zk_verifier → external APIs (application code)

##### Architectural Patterns & Principles
- Modular layering: each lib/* folder is a logical module
- Clear separation: low-level math (util, algebra) → circuit definitions → proof protocols
- Extensible circuit framework: new circuits can plug into compiler and zk layers
- Build isolation via CMake subprojects

##### Key Technologies/Frameworks
- C++17
- CMake for build orchestration
- Docker (devcontainer)
- Doxygen for API docs
- OpenSSL, Zstd (compression)
- googletest, googlebenchmark

- Core functionality: the five pillars (util, algebra, circuits, sumcheck, zk).
- Extension points: circuits/* folders (anoncred, jwt, mdoc, etc.) and compiler backends.
- How applications link against libzk (expose Public API).

- Blue: Core Math (util, algebra, ec, gf2k)
- Green: Data Structures/Parsing (arrays, cbor, merkle, random)
- Orange: Circuit Definitions (circuits/*)
- Purple: Protocols (sumcheck, zk)
- Gray: Build, CI, Docs, Tests

Step 7: Essential Elements to Include
- Arrowheads indicating dependency direction or data flow.
- Title specifying “Longfellow ZK Architecture.”
- Footnote listing external dependencies and build tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Dev Environment
    subgraph "Build & Dev Environment"
        CI["CI Pipelines"]:::gray
        Devcontainer["Devcontainer"]:::gray
        CMakeBuild["CMake Build"]:::gray
    end

    %% Core Math
    subgraph "Core Math"
        util["util"]:::blue
        algebra["algebra"]:::blue
    end

    %% Data Structures & Parsing
    subgraph "Data Structures & Parsing"
        arrays["arrays"]:::green
        cbor["cbor"]:::green
        ec["ec"]:::green
        gf2k["gf2k"]:::green
        merkle["merkle"]:::green
        random["random"]:::green
    end

    %% Circuit Definitions
    subgraph "Circuit Definitions"
        circuits["circuits"]:::orange
    end

    %% Protocols
    subgraph "Protocols"
        sumcheck["sumcheck"]:::purple
        ligero["ligero"]:::purple
        zk["zk (common/prover/verifier)"]:::purple
    end

    %% Tests & Benchmarks
    subgraph "Tests & Benchmarks"
        testing["Test Harness"]:::gray
    end

    %% Documentation
    subgraph "Documentation"
        docs["Doxygen Docs"]:::gray
    end

    %% Dependencies
    Devcontainer --> CMakeBuild
    CMakeBuild --> CI

    util -->|"field operations"| algebra
    util -->|"utils"| arrays
    util -->|"utils"| cbor
    util -->|"utils"| random

    algebra -->|"math ops"| circuits
    algebra -->|"protocol support"| sumcheck

    cbor -->|"parsed data"| circuits
    ec -->|"curve data"| circuits
    gf2k -->|"GF(2^k) ops"| circuits
    merkle -->|"commitments"| circuits

    circuits -->|"circuit AST"| sumcheck
    circuits -->|"circuit AST"| zk

    sumcheck -->|"sumcheck proof"| zk

    %% Test harness interactions
    testing -.-> util
    testing -.-> algebra
    testing -.-> arrays
    testing -.-> cbor
    testing -.-> ec
    testing -.-> gf2k
    testing -.-> merkle
    testing -.-> random
    testing -.-> circuits
    testing -.-> sumcheck
    testing -.-> zk

    %% Documentation link
    docs --> util
    docs --> circuits
    docs --> zk

    %% Click Events
    click CI "https://github.com/google/longfellow-zk/blob/main/.github/workflows/cmake-multi-platform.yml"
    click Devcontainer "https://github.com/google/longfellow-zk/blob/main/.devcontainer/devcontainer.json"
    click CMakeBuild "https://github.com/google/longfellow-zk/tree/main/lib/CMake/"
    click util "https://github.com/google/longfellow-zk/tree/main/lib/util/"
    click algebra "https://github.com/google/longfellow-zk/tree/main/lib/algebra/"
    click arrays "https://github.com/google/longfellow-zk/tree/main/lib/arrays/"
    click cbor "https://github.com/google/longfellow-zk/tree/main/lib/cbor/"
    click ec "https://github.com/google/longfellow-zk/tree/main/lib/ec/"
    click gf2k "https://github.com/google/longfellow-zk/tree/main/lib/gf2k/"
    click merkle "https://github.com/google/longfellow-zk/tree/main/lib/merkle/"
    click random "https://github.com/google/longfellow-zk/tree/main/lib/random/"
    click circuits "https://github.com/google/longfellow-zk/tree/main/lib/circuits/"
    click sumcheck "https://github.com/google/longfellow-zk/tree/main/lib/sumcheck/"
    click ligero "https://github.com/google/longfellow-zk/tree/main/lib/ligero/"
    click zk "https://github.com/google/longfellow-zk/tree/main/lib/zk/"
    click testing "https://github.com/google/longfellow-zk/tree/main/lib/testing/"
    click docs "https://github.com/google/longfellow-zk/tree/main/docs/html/"

    %% Styles
    classDef blue fill:#cee3f8,stroke:#2f6fbf,color:#0a2a66;
    classDef green fill:#d6f5d6,stroke:#28a428,color:#0a400a;
    classDef orange fill:#ffe5b4,stroke:#ff8c00,color:#663d00;
    classDef purple fill:#e5ccff,stroke:#9b59b6,color:#4a1454;
    classDef gray fill:#f2f2f2,stroke:#cccccc,color:#333333;
```
