# snapshot-labs/sx-monorepo architecture

> Architecture diagram of the GitHub repository snapshot-labs/sx-monorepo, 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/snapshot-labs/sx-monorepo
- Repository: https://github.com/snapshot-labs/sx-monorepo

## Overview

##### Main Components
- Frontend ("apps/ui"): The Snapshot X front-end implemented in Vue. It handles user interactions, presentation logic, and communicates with backend services.
- Backend API ("apps/api"): This service exposes endpoints (including GraphQL) to interact with the core business logic. It includes blockchain-related operations such as dealing with IPFS, EVM, and Starknet functionalities.
- Mana Service ("apps/mana"): A specialized backend service that appears to manage relaying and blockchain connection tasks (handled for both Ethereum and Starknet). It is responsible for managing nonces, handling relayer functionalities, and possibly for off-chain computation.
- Shared Library (packages/sx.js): A client-side library that encapsulates authentication, clients for EVM and Starknet, strategies, encoding/decoding utilities, and other blockchain integration logic. This package is used by internal applications and may be publishable as an npm package.
- Infrastructure / DevOps: Includes configuration files (Docker Compose, GitHub workflows, scripts), changesets for versioning, and project-wide configurations (tsconfig, linting, etc.).

##### Relationships and Interactions
- The Mana service acts as a relayer, bridging front-end requests with blockchain networks (EVM and Starknet). Indicate its connection to both blockchain networks and to the API service.
- For external integrations, denote connections to:
- IPFS services (as seen in multiple ipfs.ts files) for decentralized file storage.
- Optional external services such as Herodotus API for messaging across layer 1 and layer 2 solutions.

##### Architectural Patterns and Design Principles
- Monorepo Structure: Emphasize how multiple apps and packages are organized within a single repository. This facilitates reusability and coordinated versioning using changesets.
- Modularity and Extensibility: The shared library (sx.js) and the clear delineation between EVM and Starknet modules highlight an architecture that can be extended to support various blockchain interactions.

##### Relevant Technologies and Frameworks
- Frontend: Vue.js, Vite, Tailwind CSS (evidenced by configuration files and UI asset structure).
- Blockchain Integrations: Libraries and modules handling EVM contracts, Starknet interactions, and IPFS integration.
- Testing and CI/CD: GitHub workflows, changesets, Turbo (referenced by turbo.json), Docker.
- Shared Utility Libraries: Provided by packages/sx.js that contain clients, executors, strategies, and utilities supporting multiple blockchain protocols.

- Snapshot X UI (apps/ui)
- API Service (apps/api)
- Mana Service (apps/mana)
- Shared Library (sx.js)
- External Blockchain Networks (Ethereum Sepolia, Starknet Sepolia)
- External tools (IPFS, Herodotus API)
- CI/CD & Deployment Tools (GitHub workflows, Docker)
- Data flow between UI and backend services.
- Communication between backend services and external blockchain services.
- Including legends or labels that denote:
- Communication protocols (e.g., REST, GraphQL).
- Technology stacks (e.g., Vue, Node.js, TypeScript).
- Environment details (development vs. production containers).

##### Final Reminder
- This detail will aid in both understanding existing dependencies and planning for future architectural improvements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Snapshot X UI"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        API["API Service"]:::backend
        MANA["Mana Service"]:::backend
        SUB["Subgraph API"]:::backend
    end

    %% Shared Library
    LIB["Shared Library (sx.js)"]:::library

    %% External Systems
    subgraph "External Systems"
        ETH(("Ethereum Sepolia")):::blockchain
        STARK(("Starknet Sepolia")):::blockchain
        IPFS["IPFS Service"]:::external
        HERODOTUS["Herodotus API"]:::external
    end

    %% DevOps & Deployment
    subgraph "DevOps & Deployment"
        GH["GitHub Workflows"]:::deploy
        DC["Docker Compose"]:::deploy
        CONF["Other Configs"]:::deploy
        DEV["Deployment Pipeline"]:::deploy
        GH --> DEV
        DC --> DEV
        CONF --> DEV
    end

    %% Interactions between Layers
    UI -->|"REST/GraphQL"| API
    UI -->|"REST"| MANA
    UI -->|"Uses"| LIB

    API -->|"GraphQL"| SUB
    API -->|"Uses"| LIB
    MANA -->|"Uses"| LIB

    API -->|"Interacts"| IPFS
    API -->|"Interacts"| HERODOTUS

    API -->|"BlockchainOps"| ETH
    API -->|"BlockchainOps"| STARK
    MANA -->|"Relays"| ETH
    MANA -->|"Relays"| STARK

    DEV -->|"Deploys"| UI
    DEV -->|"Deploys"| API
    DEV -->|"Deploys"| MANA
    DEV -->|"Deploys"| SUB

    %% Click Events for Component Mapping
    click UI "https://github.com/snapshot-labs/sx-monorepo/tree/master/apps/ui"
    click API "https://github.com/snapshot-labs/sx-monorepo/tree/master/apps/api"
    click MANA "https://github.com/snapshot-labs/sx-monorepo/tree/master/apps/mana"
    click SUB "https://github.com/snapshot-labs/sx-monorepo/tree/master/apps/subgraph-api"
    click LIB "https://github.com/snapshot-labs/sx-monorepo/blob/master/packages/sx.js"
    click GH "https://github.com/snapshot-labs/sx-monorepo/tree/master/.github/workflows"
    click DC "https://github.com/snapshot-labs/sx-monorepo/blob/master/scripts/docker-compose.yml"
    click CONF "https://github.com/snapshot-labs/sx-monorepo/blob/master/.changeset"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef library fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef blockchain fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef deploy fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
```
