# iexecblockchaincomputing/iexec-voucher-subgraph architecture

> Architecture diagram of the GitHub repository iexecblockchaincomputing/iexec-voucher-subgraph, 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/iexecblockchaincomputing/iexec-voucher-subgraph
- Repository: https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph

## Overview

##### Project Type & Purpose
- It is focused on reading, indexing, and then exposing data via GraphQL (queriable through a GraphiQL interface) by harnessing The Graph protocol.
- The project also provides dockerized deployment and continuous integration/continuous deployment (CI/CD) pipelines using Jenkins.

##### Analyzing the File Structure
- Top-level configuration and metadata files (e.g., .dockerignore, .gitignore, package.json, JenkinsfileBuild, JenkinsfileDeploy) hint at build/deploy automation and containerized deployment.
- The “src” folder holds the core TypeScript code, for example, utilities (utils.ts) and files specific to handling vouchers (voucher.ts, voucherHub.ts).
- There’s a “tests” directory organized into unit tests for these modules indicating a well-tested code core.
- A “docker” folder with its Dockerfile and a “test-stack” directory with docker-compose setup illustrate how the system is containerized and integrated (for local testing or deployment).

##### Key Components
- The core service built in the “src” directory that indexes the blockchain VoucherHub events.
- Code generation step (npm run codegen) using the ABIs from the iexec-voucher-contracts.
- Build & Deployment Pipelines:
- Connection with CI/CD automation is vital.
- External Systems and Services:
- VoucherHub blockchain contract (the origin of events, as configured by environment variables VOUCHER_HUB_ADDRESS and VOUCHER_HUB_START_BLOCK).
- Docker Infrastructure:
- Docker container images built using the provided Dockerfile.
- The “test-stack” (docker-compose) to run a local testing environment that ties together IPFS, Graph Node, and potentially mocks of blockchain nodes.

##### Relationships and Data Flow
- The blockchain (VoucherHub contract) is the event source.
- It then communicates the data to the Graph Node, which indexes the data and provides a GraphQL API for querying.
- The entire process is automated via build and deploy pipelines orchestrated using Jenkins.
- There is also a test-stack configuration for local testing—this should be represented as an environment that simulates the production integration.

##### Architectural Patterns & Design Principles
- Separation of concerns – the code is cleanly separated into logical modules (e.g., voucher and voucherHub handling), and CI/CD is clearly separated.
- Containerization – Docker is used to encapsulate deployments ensuring consistency across environments.
- CI/CD integration – Jenkins pipelines manage the building and deployment processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Source Layer
    subgraph "Data Source Layer"
        DS("Blockchain: VoucherHub Contract"):::external
    end

    %% API/Indexing Layer
    subgraph "API/Indexing Layer"
        VS("Voucher-Subgraph Service"):::service
        VH("VoucherHub Module"):::module
        VHT("VoucherHub Tests"):::module
    end

    %% Client/Query Layer
    subgraph "Client/Query Layer"
        GQL("GraphQL API (Graph Node)"):::external
    end

    %% Storage/Infrastructure Layer
    subgraph "Storage/Infrastructure Layer"
        IPFS("IPFS Node"):::external
        CFG("Subgraph Configuration"):::config
    end

    %% Build & Deployment Layer
    subgraph "Build & Deployment Layer"
        JB("Jenkins Build Pipeline"):::cicd
        JD("Jenkins Deployment Pipeline"):::cicd
        DO("Docker Infrastructure"):::docker
        TE("Test-Stack Environment"):::docker
    end

    %% Relationships and Data Flow
    DS -->|"emits_events"| VS
    VS -->|"uses"| VH
    VS -->|"uses"| VHT
    VS -->|"indexes_to"| GQL
    VS -->|"stores_in"| IPFS
    CFG -->|"configs"| GQL
    CFG -->|"configs"| IPFS
    JB -->|"builds"| DO
    DO -->|"runs"| VS
    JD -->|"deploys"| DO
    JB -->|"triggers"| JD
    DO -->|"orchestrates"| TE

    %% Click Events
    click VS "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/tree/main/src/"
    click VH "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/blob/main/src/voucherHub.ts"
    click VHT "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/tree/main/tests/unit/voucherhub/"
    click JB "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/tree/main/JenkinsfileBuild"
    click JD "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/tree/main/JenkinsfileDeploy"
    click DO "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/tree/main/docker/Dockerfile"
    click TE "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/blob/main/test-stack/docker-compose.yml"
    click CFG "https://github.com/iexecblockchaincomputing/iexec-voucher-subgraph/blob/main/subgraph.template.yaml"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef service fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#aff,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fc9,stroke:#333,stroke-width:2px;
    classDef docker fill:#cfc,stroke:#333,stroke-width:2px;
    classDef config fill:#ffc,stroke:#333,stroke-width:2px;
```
