# privacy-scaling-explorations/maci architecture

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

- Interactive diagram: https://gitdiagram.com/privacy-scaling-explorations/maci
- Repository: https://github.com/privacy-scaling-explorations/maci

## Overview

##### Components Identification
- On-Chain Components:
- Smart Contracts (found in packages/contracts) that implement the core anti-collusion voting logic, including deployment tasks, gatekeepers, poll factories, and message processors.
- Off-Chain Services:
- Coordinator Service (apps/coordinator): Responsible for coordinating message processing, authentication, and integrating with the on-chain contracts.
- Relayer Service (apps/relayer): Handles message relaying between users and the blockchain.
- Supporting Libraries/Modules:
- Cryptography (packages/crypto): Low-level cryptographic functions and utilities.
- Circuits (packages/circuits): zk-SNARK circuits (written in circom) used for zero-knowledge proofs.
- Core Business Logic (packages/core): Implements vote tallying, message processing, and the MACI state machine (via MaciState).
- Domain Objects (packages/domainobjs): Defines high-level classes to represent domain-specific entities (e.g., ballots, commands, keys).
- CLI Tool (packages/cli): Command-line interface that enables deployment and user interactions with the protocol.
- SDK (packages/sdk): Developer toolkit for integrating and interacting with MACI.
- Testing Suite (packages/testing): Comprehensive integration and unit tests.
- User Interface & Documentation:
- Website (apps/website): Provides documentation, blogs, and guides for developers and integrators.

##### Relationships and Interactions
- That the Coordinator and Relayer services interact with the contracts deployed on the blockchain (via Hardhat configurations and deployment scripts).
- Underlying dependency: The business logic (core), cryptographic operations (crypto), and zk-SNARK circuits (circuits) all feed into how the protocol processes and secures vote messages.

##### Architectural Patterns and Design Principles
- Modular / Workspace Structure: Emphasize the separation of concerns across different packages (each with its own unit tests, deployment scripts, and CI workflows).
- Layered Architecture:
- Presentation/Interface Layer (CLI, Website, SDK)
- Application/Service Layer (Coordinator, Relayer)
- Domain/Logic Layer (Core, Domain Objects, Cryptography, Circuits)
- CI/CD Integration: Include a note that automated pipelines (under .github/workflows) are used to build, test, and deploy components.

##### Relevant Technologies and Frameworks
- TypeScript is the primary programming language.
- Hardhat for smart contract compilation, testing, and deployment.
- Circom for writing and compiling zk-SNARK circuits.
- NestJS (implied by nest-cli.json files in coordinator and relayer) for structuring the backend services.
- pnpm as the mono-repo/package manager.
- GitHub Actions for CI/CD workflows.

##### Detail and Clarity
- Component is clearly defined with its purpose in the system.
- Directional dependencies are illustrated (for example, show that the Core business logic depends on the cryptographic and circuit functionalities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/Interface Layer
    subgraph "Presentation/Interface Layer"
        CLI("CLI Tool"):::interface
        SDK("SDK"):::interface
        Website("Website"):::interface
    end

    %% Application/Service Layer
    subgraph "Application/Service Layer"
        Coord("Coordinator Service"):::service
        Relayer("Relayer Service"):::service
    end

    %% Protocol Library Layer
    subgraph "Protocol Library"
        Core("Core Business Logic"):::library
        Crypto("Cryptography Library"):::library
        Circuits("Circuits (zk-SNARK circuits)"):::library
        Domain("Domain Objects Module"):::library
        Testing("Testing Suite"):::testing
    end

    %% Data/Infrastructure Layer
    subgraph "Data/Infrastructure Layer"
        Contracts("Smart Contracts"):::infrastructure
        Subgraph("Subgraph Indexer"):::infrastructure
    end

    %% User Interfaces to Application Services
    CLI -->|"calls"| Coord
    CLI -->|"calls"| Relayer
    SDK -->|"calls"| Coord
    SDK -->|"calls"| Relayer
    Website -->|"calls"| Coord
    Website -->|"calls"| Relayer

    %% Application Services to On-Chain Components
    Coord -->|"interacts"| Contracts
    Relayer -->|"interacts"| Contracts

    %% Blockchain event flow
    Contracts -->|"emits events"| Subgraph
    Subgraph -->|"provides data"| Website
    Subgraph -->|"provides data"| CLI
    Subgraph -->|"provides data"| SDK

    %% Application Services using Protocol Library components
    Coord -->|"processes messages"| Core
    Relayer -->|"processes messages"| Core

    %% Protocol Library internal dependencies
    Crypto -->|"feeds"| Core
    Circuits -->|"feeds"| Core
    Domain -->|"feeds"| Core
    Testing -->|"validates"| Core

    %% Styles
    classDef interface fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef library fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infrastructure fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef testing fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/cli"
    click SDK "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/sdk"
    click Website "https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/website"
    click Coord "https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/coordinator"
    click Relayer "https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/relayer"
    click Contracts "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/contracts"
    click Subgraph "https://github.com/privacy-scaling-explorations/maci/tree/dev/apps/subgraph"
    click Core "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/core"
    click Crypto "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/crypto"
    click Circuits "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/circuits"
    click Domain "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/domainobjs"
    click Testing "https://github.com/privacy-scaling-explorations/maci/tree/dev/packages/testing"
```
