# tejaaswini/zeroking architecture

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

- Interactive diagram: https://gitdiagram.com/tejaaswini/zeroking
- Repository: https://github.com/tejaaswini/zeroking

## Overview

Overview:
ZeroKing is a trustless, privacy-preserving chess game that leverages zero‐knowledge cryptography to verify game moves and user actions. It has a full‐stack architecture with a frontend built on SvelteKit (in the ui directory) and a backend contracts layer (in the contracts directory) containing the core game logic, state management, and move validation. The UI interacts with a zkApp client (using o1js and zkAppWorker) to communicate with Mina protocols and enforce zero‐knowledge proofs.

Key Components:
##### Contracts (Backend – zk Proofs & Game Logic)
- Board Module (contracts/src/Board/Board.ts):
– Likely functions: initializeBoard(), renderBoard(); could include functions such as updateBoardState() based on moves.
- Chess Module (contracts/src/Chess.ts & contracts/src/Chess.test.ts):
– Central chess game engine. Possible functions: startGame(), processMove(), endGame().
- GameLogic Module (contracts/src/GameLogic/GameLogic.ts & GameLogic.test.ts):
– Contains logic for move validation and enforcing game rules. Expected functions: validateMove(), checkGameStatus(), triggerGameOver().
- GameState Module (contracts/src/GameState/GameState.ts & GameState.test.ts):
– Manages the state of the game. Functions might include: updateGameState(), getCurrentState(), resetGameState().
- Move Module (contracts/src/Move/Move.ts & Path.ts & tests):
– Handles move details and path validation. Functions such as: calculateMovePath(), validatePath(), parseMoveInput().
- Piece Module (contracts/src/Piece/Piece.ts & tests):
– Defines chess pieces and their behavior. Get functions like: getPieceType(), determineLegalMoves().
- PlayerState Module (contracts/src/PlayerState/PlayerState.ts & tests):
– Manages individual player information. Expected functions: updatePlayerStatus(), recordPlayerAction().
- Module (contracts/src/Position/Position.ts & tests):
– Handles board coordinates and positions. Likely includes: convertCoordinate(), validatePosition().

##### UI (Frontend – SvelteKit Application)
- Routes:
– Landing Page (+page.svelte): Provides .edu email login using zkEmail proof.
– Game Pages (game/+page.svelte, Board.svelte, DashboardLayout.svelte, etc.): The core Chess UI where players interact.
- UI Components:
– Reusable components (e.g., AuroConnect.svelte, ToastModal.svelte) and support for notifications (using French Toast).
- zkApp Integration:
– Located in ui/src/lib/zkapp (ZkappWorker.ts and ZkappWorkerClient.ts): Provides client-side integration with the zkApp for processing zero-knowledge proofs and interactions with Mina.
- Utility Functions:
– Additional UI libraries (like lib/Stopwatch.ts, lib/ellipsis.ts) to support user interactions and visual feedback.

##### External Interfaces & Technologies
- zkEmail: Provides .edu-only login through a zero-knowledge proof generation for identity verification.
- Mina blockchain: The underlying platform where on-chain move validation occurs.
- Wallet Integration: The project requires a Mina wallet (Auro) to interact with the zkApp.
- Notification System (French Toast): For clean notifications during game events.
- Testing: Jest configuration indicates thorough unit tests across GameLogic, Board, GameState, etc.

Relationships and Data Flow:
- The UI initiates user interactions:
- A user logs in using an .edu email, triggering zkEmail proof generation.
- On successful login, the interface displays the chess board and game controls.
- The UI communicates with the zkApp client layer (via ZkappWorker and ZkappWorkerClient) to forward move inputs.
- The zkApp client then interacts with the underlying contracts (chain or simulated layer) that run the game logic (modules such as Chess, GameState, Move, etc.)
- Between modules, functions like processMove(), validateMove(), updateGameState() are called to ensure each move is provably correct within the zero-knowledge circuit.
- There is also interaction with external services like the Mina blockchain network for move validation and, eventually, NFT minting for game outcomes.

Design Principles and Architectural Patterns:
- Separation of Concerns: UI components handle interactions and presentation, while smart-contract-like modules handle game logic, move validation, and state management.
- Modular Design: Each functional domain (Board, GameLogic, GameState, Move, Piece, PlayerState, Position) is encapsulated in its module.
- Test-Driven Development: Each module has accompanying tests (e.g., *.test.ts files) ensuring robust, verifiable logic.
- Event-Driven Flow: UI events (login, paper move submission, game resignation) generate data flows to backend modules that process and update game state.

- UI Layer:
- zkApp Client Layer:
- Game Logic / Contracts Layer:
- Board Module (with functions: initializeBoard(), updateBoardState())
- Chess Module (startGame(), processMove(), endGame())
- GameLogic Module (validateMove(), checkGameStatus(), triggerGameOver())
- GameState Module (updateGameState(), getCurrentState(), resetGameState())
- Move Module (calculateMovePath(), validatePath(), parseMoveInput())
- Piece Module (getPieceType(), determineLegalMoves())
- PlayerState Module (updatePlayerStatus(), recordPlayerAction())
- Module (convertCoordinate(), validatePosition())
- External Interfaces:

- UI → zkApp Client: For sending game moves and handling proofs.
- zkApp Client → Contracts/Smart Logic: For invoking functions like processMove() and validateMove().
- Contracts → External Blockchain: For on-chain move validations and subsequent notifications.
- External responses (game over events, NFT minting triggers) flow back through the chain to UI.

##### Naming Functions
- In the Contracts section, label:
– Board: initializeBoard(), renderBoard()
– Chess: startGame(), processMove(), endGame()
– GameLogic: validateMove(), checkGameStatus(), triggerGameOver()
– GameState: updateGameState(), getCurrentState(), resetGameState()
– Move: calculateMovePath(), validatePath(), parseMoveInput()
– Piece: getPieceType(), determineLegalMoves()
– PlayerState: updatePlayerStatus(), recordPlayerAction()
– Position: convertCoordinate(), validatePosition()

For this full-stack chess application:
- Clear segregation between the user interface and the backend (contracts) handling zero-knowledge proofs.
- Integration points with external services like zkEmail for secure login and Mina for blockchain interactions.
- Modular design of game logic, with each domain (Board, Move, etc.) treated as an independent component.

Final Notes for the Principal Software Engineer:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% SvelteKit Frontend
    subgraph "SvelteKit Frontend"
        UI1["Landing Page & Layout\n(.edu login via zkEmail)"] 
        UI2["Game UI\n(Chess Board, Dashboard)"] 
        UI3["Connect Page\n(Connect via Auro)"]
        UI4["UI Components\n(AuroConnect, ToastModal)"]
        UI5["Utilities\n(Stopwatch, ellipsis, interaction)"]
    end

    %% zkApp Client Layer
    subgraph "zkApp Client"
        ZK1["ZkappWorker"]
        ZK2["ZkappWorkerClient"]
    end

    %% Contracts & Game Logic
    subgraph "Contracts & Game Logic"
        C1["Board Module\n(initializeBoard(), renderBoard(), updateBoardState())"]
        C2["Chess Module\n(startGame(), processMove(), endGame())"]
        C3["GameLogic Module\n(validateMove(), checkGameStatus(), triggerGameOver())"]
        C4["GameState Module\n(updateGameState(), getCurrentState(), resetGameState())"]
        C5["Move Module\n(calculateMovePath(), validatePath(), parseMoveInput())"]
        C6["Piece Module\n(getPieceType(), determineLegalMoves())"]
        C7["PlayerState Module\n(updatePlayerStatus(), recordPlayerAction())"]
        C8["Position Module\n(convertCoordinate(), validatePosition())"]
    end

    %% External Services
    subgraph "External Services"
        E1["Mina Blockchain"]
        E2["zkEmail"]
        E3["Wallet (Auro)"]
    end

    %% Connections between Frontend and zkApp Client
    UI1 ---|"triggers login"| E2
    UI2 ---|"sends move input"| ZK1
    UI2 ---|"sends move input"| ZK2

    %% Connection from External Wallet to zkApp Client
    E3 ---|"wallet interaction"| ZK1

    %% Connection from zkApp Client to Contracts & Game Logic
    ZK1 ---|"processMove()"| C2
    ZK2 ---|"validateMove()"| C3

    %% Internal Contracts interactions (illustrative flow)
    C2 ---|"updates state"| C4
    C3 ---|"triggers game rules"| C1
    C4 ---|"state update"| UI2
    C5 ---|"parses moves"| C2
    C6 ---|"piece validation"| C3
    C7 ---|"player actions"| C4
    C8 ---|"position check"| C1

    %% Contracts interacting with External Services
    C2 ---|"on-chain validation"| E1
    E1 ---|"game events/NFT triggers"| C4

    %% External response for authentication
    E2 ---|"auth proof"| UI1

    %% Styles
    class UI1,UI2,UI3,UI4,UI5 frontend
    class ZK1,ZK2 zkclient
    class C1,C2,C3,C4,C5,C6,C7,C8 backend
    class E1,E2,E3 external

    %% Click Events for Contracts & Game Logic
    click C1 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/Board/Board.ts"
    click C2 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/Chess.ts"
    click C3 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/GameLogic/GameLogic.ts"
    click C4 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/GameState/GameState.ts"
    click C5 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/Move/Move.ts"
    click C6 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/Piece/Piece.ts"
    click C7 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/PlayerState/PlayerState.ts"
    click C8 "https://github.com/tejaaswini/zeroking/blob/main/contracts/src/Position/Position.ts"

    %% Click Events for Frontend Components & UI
    click UI1 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/routes/+page.svelte"
    click UI2 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/routes/game/Board.svelte"
    click UI3 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/routes/connect/+page.svelte"
    click UI4 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/lib/components/general/AuroConnect.svelte"
    click UI5 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/lib/Stopwatch.ts"

    %% Click Events for zkApp Client Integration
    click ZK1 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/lib/zkapp/ZkappWorker.ts"
    click ZK2 "https://github.com/tejaaswini/zeroking/blob/main/ui/src/lib/zkapp/ZkappWorkerClient.ts"
```
