# node101-io/zkvot architecture

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

- Interactive diagram: https://gitdiagram.com/node101-io/zkvot
- Repository: https://github.com/node101-io/zkvot

## Overview

##### Main Components
- Frontend (User Application): Represented by the “apps/webapp” folder, this Next.js–based web application is the primary user interface for voters and election creators. It handles routing, user interactions, and presentation layers.
- Backend: Found under “apps/backend”, this component provides API endpoints and controllers for block information, elections, votes, and scheduled (cron) jobs. It serves the webapp as well as other parts of the system.
- Aggregator: “apps/aggregator” is responsible for handling distributed computations such as zero-knowledge aggregations. It processes and compiles zk-programs that are likely used to ensure the cryptographic integrity of the votes.
- CLI Tool: The “apps/cli” package offers command-line functions and utilities (including commands for counting, logs, and results) to interact with the aggregated election data and manage the underlying blockchain/data layer infrastructure (e.g., “da-layers” for avail and celestia).
- Shared Libraries/Packages: The “packages” folder (with subdirectories like “backend-utils”, “core”, and “config”) contains common utilities, models, aggregation programs, election contracts, and zero-knowledge proof functionality. These packages are used across all apps to maintain consistency and reduce duplicated logic.

##### Relationships and Interactions
- Data Flow: The webapp communicates with the backend via REST API endpoints. The backend, in turn, is designed with controllers that interact with different business logic modules (from “packages/backend-utils” and “packages/core”).
- Aggregation Process: The aggregator application processes votes and compilation of zk-programs. It likely receives input from the backend or directly from data sources and, once aggregated, feeds back into backend processing or CLI commands.
- CLI Coordination: The CLI tool offers administration and aggregation commands (e.g., counting votes, retrieving logs, and handling distributed aggregation) and interacts with backend libraries and the da-layer utilities provided for avail and celestia nodes. It also handles Docker file management and configuration for the light-node setups.
- Modular Utilities: All apps reference shared libraries (from “packages/core” and “packages/backend-utils”) to perform essential tasks like vote verification, key generation, and data encoding/decoding.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each app (webapp, backend, aggregator, CLI) is self-contained but shares common logic via packages. This promotes separation of concerns and reusability.
- Microservice-Inspired Segmentation: Although not separate microservices in deployment per se, the delineation of responsibilities (frontend vs. backend vs. aggregation processing) and the existence of CLI-based management commands imply a loosely-coupled design structure.
- Distributed Computation & Zero Knowledge: Special emphasis on zk-program compilation, verification keys, and aggregation algorithms indicates an architectural focus on client-side trustless computation.
- Containerization: The presence of Dockerfiles and docker-compose configurations (especially for the “light-node” in both avail and celestia subsystems) suggests containerized deployment for the data anchoring layers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Components
    A["Webapp (Next.js)"]:::frontend
    B["Backend API (Express/Node.js)"]:::backend
    C["Aggregator (zk aggregation)"]:::aggregator
    D["CLI Tool"]:::cli

    %% Shared Libraries Cluster
    subgraph "Shared Libraries & Utilities"
        BU["Backend Utils"]:::utils
        CO["Core Library"]:::utils
        CF["Config Utils"]:::utils
    end

    %% Data Flow between Main Components
    A -->|"REST_API"| B
    B -->|"aggregates"| C
    D -->|"manage"| B
    D -->|"trigger"| C

    %% Connections to Shared Libraries (dotted arrows)
    A -.->|"uses"| BU
    A -.->|"uses"| CO
    A -.->|"uses"| CF

    B -.->|"uses"| BU
    B -.->|"uses"| CO
    B -.->|"uses"| CF

    C -.->|"uses"| BU
    C -.->|"uses"| CO
    C -.->|"uses"| CF

    D -.->|"uses"| BU
    D -.->|"uses"| CO
    D -.->|"uses"| CF

    %% Click Events
    click A "https://github.com/node101-io/zkvot/tree/main/apps/webapp"
    click B "https://github.com/node101-io/zkvot/tree/main/apps/backend"
    click C "https://github.com/node101-io/zkvot/tree/main/apps/aggregator"
    click D "https://github.com/node101-io/zkvot/tree/main/apps/cli"
    click BU "https://github.com/node101-io/zkvot/tree/main/packages/backend-utils"
    click CO "https://github.com/node101-io/zkvot/tree/main/packages/core"
    click CF "https://github.com/node101-io/zkvot/tree/main/packages/config"

    %% Styles
    classDef frontend fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef aggregator fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef cli fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
```
