# albertobas/zk-connect-four architecture

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

- Interactive diagram: https://gitdiagram.com/albertobas/zk-connect-four
- Repository: https://github.com/albertobas/zk-connect-four

## Overview

- Front-end Application: Mark the Next.js React app (found under apps/web). This is responsible for the user interface, state management, API endpoints (inside pages/api), and interactions with the blockchain.
- Smart Contracts Backend: Represent the Solidity contracts located in apps/contracts. Include the Hardhat configuration, deploy scripts, and deployment artifacts (deployment JSON files). Show that these contracts are deployed on a blockchain network (e.g., Sepolia or localhost), with data flows related to game state and verification.
- Circuits Module: Capture the Circom circuits under apps/circuits. Note that these circuits include the game logic needed to generate zk-SNARK proofs (e.g., the connect-four.circom file) and also the related unit tests and export scripts. Include the dependency on the Powers of Tau file (in apps/circuits/ptau) necessary for setting up circuit parameters.
- Machine Learning / DQN Agent: Represent the ML component located within apps/web/model. Highlight that it comprises Python scripts (agent.py, training.py, etc.), Jupyter notebooks, and exported neural network models. This component trains and generates the policy (and corresponding ONNX models) used by the UI for providing an AI opponent.
- Shared Packages and Configurations: Optionally add a component for shared packages (in packages/) that contain utility libraries (e.g., eslint configurations, tsconfig, UI components in packages/ui) used across workspaces. This shows modularity and reuse across the front end and possibly contracts/circuits configuration.

##### Relationships and Data Flow
- That when a game reaches a conclusion, the UI interacts with the smart contracts for submitting or verifying zk-SNARK proofs. Connect the circuits module to both the UI and the smart contracts to show this interaction.
- AI component feeding into the user experience by having the front end request game moves from the DQN agent and use the ML predictions (including loading models, e.g., from ONNX files in apps/web/model/exports) to play against users.

##### Architectural Patterns and Important Technologies
- Separation of concerns among the three pillars: proof generation (Circuits), blockchain logic (Smart Contracts), and user interaction (Next.js front end).
- Integration points:
- The Circom circuits are a critical part of validating game outcomes via zk-SNARK proofs.
- The Hardhat-based smart contract layer manages game state and proof verification on-chain.
- The Next.js application bridges user actions with blockchain calls and manages state updates.
- The machine learning module implements reinforcement learning to train a DQN agent for game play. It also exports trained models which are consumed by the front end.
- Key technologies near each component:
- Circuits: Circom, TypeScript (for tests and scripts)
- Contracts: Solidity, Hardhat, TypeScript (for deploy scripts)
- Web: Next.js, React, TypeScript, PostCSS
- ML: Python, PyTorch, ONNX
- Additional shared tools: eslint, Prettier, pnpm, Turborepo

##### Essential Elements
- Component labels for each module and sub-system.
- A clear separation of the full-stack layers (front end, backend smart contracts, circuits proof system, and ML module).
- Notations for external dependencies (e.g., the Powers of Tau file dependency, external blockchain networks like Sepolia or localhost emulation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        FE["Next.js Front-end (apps/web)"]:::frontend
        ML["ML/DQN Agent (apps/web/model)"]:::ml
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        SC["Smart Contracts (apps/contracts)"]:::contracts
    end

    %% Zero-Knowledge Proof System
    subgraph "ZK Proof System"
        CM["Circuits (apps/circuits)"]:::circuits
        PTAU["Powers of Tau (apps/circuits/ptau)"]:::circuitDeps
    end

    %% Shared Configurations
    subgraph "Shared Configurations"
        SP["Shared Packages (packages)"]:::shared
    end

    %% Data Flow
    FE -->|"GameActions/ProofReq"| SC
    FE -->|"ProofGen/Validation"| CM
    CM -->|"ProofData"| SC
    FE -->|"RequestAIMove"| ML
    ML -->|"AIMoveData"| FE
    CM -->|"SetupParams"| PTAU

    %% Click Events
    click FE "https://github.com/albertobas/zk-connect-four/tree/main/apps/web"
    click SC "https://github.com/albertobas/zk-connect-four/tree/main/apps/contracts"
    click CM "https://github.com/albertobas/zk-connect-four/tree/main/apps/circuits"
    click PTAU "https://github.com/albertobas/zk-connect-four/tree/main/apps/circuits/ptau"
    click ML "https://github.com/albertobas/zk-connect-four/tree/main/apps/web/model"
    click SP "https://github.com/albertobas/zk-connect-four/tree/main/packages"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#1B95E0,stroke-width:2px;
    classDef contracts fill:#F7D6AE,stroke:#E09F1B,stroke-width:2px;
    classDef circuits fill:#D6F7AE,stroke:#1BE01B,stroke-width:2px;
    classDef ml fill:#F7AECF,stroke:#E01B95,stroke-width:2px;
    classDef shared fill:#E0E0E0,stroke:#808080,stroke-width:2px;
    classDef circuitDeps fill:#C1E1C1,stroke:#28A745,stroke-width:2px;
```
