# kaleababayneh/zkuni architecture

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

- Interactive diagram: https://gitdiagram.com/kaleababayneh/zkuni
- Repository: https://github.com/kaleababayneh/zkuni

## Overview

##### Project Type and Purpose
- zkUni is a privacy-preserving, single-page admissions system (a web-based full-stack app with most logic on the client) that uses a Noir ZK circuit to compute and prove a stable matching (Gale-Shapley) with ElGamal encrypted results.
- Key Use Case: Students and colleges submit hidden preference lists; the system computes an optimal matching inside a ZK circuit, encrypts matches per recipient, and generates a proof of correct matching/encryption without revealing any preferences.

##### File-Structure Analysis
- Top Level:
- package.json, bun.lock, package-lock.json, vite.config.js
→ Frontend build & dependency management (Vite + Node).
- index.html, index.js, stable.js, new.js, key-generate.js
→ Client entry-point, preference collection, key gen, proof invocation scripts.
- circuit/
- Nargo.toml
→ Noir circuit project config.
- src/elgamal.nr, src/main.nr
→ Noir code for ElGamal encryption & Gale-Shapley matching.
- target/circuit.json
→ Compiled circuit artifact consumed by JS prover/runtime.

##### README Insights
- Technologies: Noir for ZK logic, ElGamal for encryption, JavaScript/TypeScript for client logic, Vite for bundling.
- Architecture Intent: Purely trustless, zero-knowledge matching; proof ⇒ correctness of both matching algorithm and encryption steps.

##### Main Components & Relationships
a. Frontend Web Application
- index.html + JS modules (index.js, stable.js, new.js)
- Serves UI for preference entry, triggering cryptographic routines.
b. Key-Generation Module (key-generate.js)
- Generates ElGamal key pairs for students & colleges.
c. ZK Prover Runtime (noir-client + WASM)
- Loads circuit.json, takes inputs (prefs + keys), runs witness gen & proof.
d. Noir ZK Circuit (main.nr + elgamal.nr)
- Implements Gale-Shapley + ElGamal encryption inside the proof.
e. Proof Verifier (noir-client or embedded verifier)
- Verifies the proof without revealing any inputs.
f. Delivery & Decryption
- Encrypted match outputs are distributed; recipients use private keys to decrypt.

##### Architectural Patterns & Principles
- Separation of Concerns:
- UI vs. Cryptographic Logic vs. Circuit definition.
- Zero-Knowledge Pattern:
- Prover/Verifier roles clearly separated.
- Client-Heavy Compute:
- Moves both matching and proof generation to the browser/Node, avoids a trusted backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external

    %% Frontend Application
    subgraph "Frontend Web Application"
        direction TB
        UI_HTML["index.html"]:::ui
        UI_Index["index.js"]:::ui
        UI_Stable["stable.js"]:::ui
        UI_New["new.js"]:::ui
    end

    %% Frontend Build Config
    subgraph "Frontend Build Config"
        direction TB
        Pkg["package.json"]:::config
        Bun["bun.lock"]:::config
        PkgLock["package-lock.json"]:::config
        Vite["vite.config.js"]:::config
    end

    %% Key Generation
    KG["key-generate.js\n(Key-Generation Module)"]:::crypto

    %% Noir Circuit Definition and Artifact
    subgraph "Noir Circuit Definition & Artifact"
        direction TB
        Nargo["Nargo.toml"]:::circuit
        MainNR["src/main.nr"]:::circuit
        ElGNR["src/elgamal.nr"]:::circuit
        CircuitJSON["circuit.json"]:::artifact
    end

    %% ZK Prover and Verifier
    Prover["ZK Prover Runtime\n(WASM Engine)"]:::crypto
    Verifier["Proof Verifier\n(WASM Engine)"]:::crypto

    %% Storage / Delivery
    Storage["Encrypted Results Delivery"]:::data

    %% Data Flows
    User -->|"enter preferences"| UI_HTML
    UI_HTML -->|"loads scripts"| UI_Index
    UI_Index -->|"collects prefs"| UI_Stable
    UI_Stable -->|"prefs"| KG
    KG -->|"public/private keys"| UI_Index
    UI_Index -->|"prefs + pub keys + circuit.json"| Prover
    Nargo -->|"build time"| CircuitJSON
    CircuitJSON -->|"circuit artifact"| Prover
    MainNR -->|"circuit logic"| Prover
    ElGNR -->|"encryption logic"| Prover
    Prover -->|"proof"| Verifier
    Verifier -->|"verification result"| UI_Index
    UI_Index -->|"encrypted matches"| Storage

    %% Click Events
    click UI_HTML "https://github.com/kaleababayneh/zkuni/blob/main/index.html"
    click UI_Index "https://github.com/kaleababayneh/zkuni/blob/main/index.js"
    click UI_Stable "https://github.com/kaleababayneh/zkuni/blob/main/stable.js"
    click UI_New "https://github.com/kaleababayneh/zkuni/blob/main/new.js"
    click KG "https://github.com/kaleababayneh/zkuni/blob/main/key-generate.js"
    click CircuitJSON "https://github.com/kaleababayneh/zkuni/blob/main/circuit/target/circuit.json"
    click Nargo "https://github.com/kaleababayneh/zkuni/blob/main/circuit/Nargo.toml"
    click MainNR "https://github.com/kaleababayneh/zkuni/blob/main/circuit/src/main.nr"
    click ElGNR "https://github.com/kaleababayneh/zkuni/blob/main/circuit/src/elgamal.nr"
    click Pkg "https://github.com/kaleababayneh/zkuni/blob/main/package.json"
    click Bun "https://github.com/kaleababayneh/zkuni/blob/main/bun.lock"
    click PkgLock "https://github.com/kaleababayneh/zkuni/blob/main/package-lock.json"
    click Vite "https://github.com/kaleababayneh/zkuni/blob/main/vite.config.js"

    %% Styling
    classDef ui fill:#ADD8E6,stroke:#000
    classDef crypto fill:#90EE90,stroke:#000
    classDef circuit fill:#FFA500,stroke:#000
    classDef artifact fill:#FFD700,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
    classDef data fill:#FFFFFF,stroke:#000
    classDef external fill:#CCCCCC,stroke:#000,stroke-dasharray: 5 5
```
