# giveth/devouch-be architecture

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

- Interactive diagram: https://gitdiagram.com/giveth/devouch-be
- Repository: https://github.com/giveth/devouch-be

## Overview

##### Project type and purpose
- DeVouch-BE is a backend microservice in Giveth’s ecosystem. It uses a combination of a blockchain-event ingestion pipeline (Subsquid), scheduled import jobs, a PostgreSQL database, and a GraphQL API to power a decentralized attestation/vouching system.
- Its primary use cases are: importing project metadata from external sources (Giveth, Gitcoin, RetroFund, RetroList), validating attestors via EAS attestations on Ethereum, and exposing vouch/flag data over GraphQL.

##### File structure
- Top-level config & infra:
- Dockerfile, docker-compose.yml (service orchestration)
- Caddyfile (reverse proxy)
- .github/workflows (CI/CD pipelines)
- squid.yaml (Subsquid pipeline configuration)
- Database migration layer:
- db/migrations & scripts (create tables, seed organizations)
- ABI definitions:
- abi/ & src/abi (EAS and Schema contract ABIs + multicall support)
- Scheduler & import features:
- src/features/import-projects (per-source modules: Giveth, Gitcoin, RetroFund, RetroList)
- fetch-eas-abi.sh (helper)
- Event processor:
- src/processor.ts, src/main.ts, squid.yaml (Subsquid handlers for attest/revoke events)
- src/controllers & src/controllers/utils (map events → database)
- API server:
- schema.graphql, src/server-extension (GraphQL resolvers), src/helpers/request.ts
- Persistence & models:
- src/model/generated (ORM models), src/helpers/db.ts
- Tests:
- src/test (bootstrap, unit tests)

##### README for additional insights
- Confirms a three-flow architecture:
1) scheduled imports
2) attestor validation via EAS
3) project attestation processing
- Tech stack: Node.js/TypeScript, Subsquid, PostgreSQL, GraphQL, ethers.js, Jest.
- External dependencies: Ethereum RPC endpoint, various project-source APIs, IPFS.

a. Main components
- Scheduler/Importer Service
- Subsquid Event Processor
- Business Logic Controllers/Services
- PostgreSQL Database
- GraphQL API Server
- External Services:
- Ethereum RPC & EAS contracts
- Project-source APIs (Giveth, Gitcoin, RF4, RF5, RetroList)
- IPFS gateway (if used)
b. Relationships and interactions
1. Scheduler triggers import jobs → import modules fetch project lists from external APIs → controllers transform & upsert into DB.
2. Ethereum RPC streams events → Subsquid pipeline (processor.ts) → controllers parse attest/revoke → map to DB.
3. Clients query GraphQL endpoint → server-extension resolvers read/write DB → optional blockchain writes via ethers.js/EAS.
c. Architectural patterns and design principles
- Modular “feature” folder per integration source (single-responsibility).
- Event-driven pipeline for on-chain events (Subsquid).
- Layered architecture: controllers/services separate database helpers, ABI helpers, model helpers.
- Clean separation of ingestion, processing, and API layers.
d. Key technologies and libraries
- Subsquid (blockchain indexing)
- TypeORM or generated ORM models
- GraphQL with custom resolvers
- ethers.js for contract interactions
- Node cron (import schedule)
- Docker + Docker Compose for deployment

##### Be detailed but focused
- Break large blocks (e.g., “Import Scheduler”) into subcomponents (e.g., “Giveth Import,” “Gitcoin Import”) if space permits.
- Essential external connections (RPC, EAS, HTTP APIs).
- Don’t overcomplicate: emphasize the three flows (import, on-chain, API) and how they converge on the DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Import Layer"
        direction TB
        ImportScheduler["Import Scheduler"]:::internal
        subgraph "Import Modules"
            direction TB
            Giveth["Giveth Import"]:::internal
            Gitcoin["Gitcoin Import"]:::internal
            RetroFund["RetroFund Import"]:::internal
            RetroList["RetroList Import"]:::internal
            Gardens["Gardens Import"]:::internal
            RPGF["RPGF Import"]:::internal
        end
        Shell["fetch-eas-abi.sh"]:::internal
    end

    subgraph "Event Processing"
        direction TB
        SubSquid["Subsquid Processor"]:::internal
        EventControllers["Event Controllers & Utils"]:::internal
        Mappings["Event-to-Model Mappings"]:::internal
    end

    subgraph "API Layer"
        direction TB
        GraphQLServer["GraphQL API Server"]:::internal
        ExtHelpers["GraphQL Schema Extensions"]:::internal
    end

    %% Central Database
    Postgres["PostgreSQL Database"]:::db
    Migrations["DB Migrations"]:::db
    DbHelpers["DB Helpers"]:::internal
    ORM["ORM Models"]:::internal

    %% External Services
    EthereumRPC[(Ethereum RPC & EAS Contracts)]:::external
    ProjectAPIs[(Project-source APIs)]:::external
    IPFS[(IPFS Gateway)]:::external
    Client[(GraphQL Client)]:::external

    %% Flows
    Client -->|"queries"| GraphQLServer
    GraphQLServer -->|"reads/writes"| Postgres
    ImportScheduler -->|"triggers"| Giveth
    ImportScheduler --> Gitcoin
    ImportScheduler --> RetroFund
    ImportScheduler --> RetroList
    ImportScheduler --> Gardens
    ImportScheduler --> RPGF
    Giveth -->|"upserts"| Postgres
    Gitcoin --> Postgres
    RetroFund --> Postgres
    RetroList --> Postgres
    Gardens --> Postgres
    RPGF --> Postgres
    EthereumRPC -->|"events"| SubSquid
    SubSquid --> EventControllers
    EventControllers --> Mappings
    Mappings -->|"updates"| Postgres

    %% Helpers and Models
    DbHelpers --> Postgres
    ORM --> Postgres

    %% Infrastructure & Tests
    Infra["Config & Infra"]:::external
    Tests["Test Suite"]:::internal

    Infra -.-> ImportScheduler
    Infra -.-> SubSquid
    Infra -.-> GraphQLServer
    Tests -.-> ImportScheduler
    Tests -.-> EventControllers
    Tests -.-> GraphQLServer

    %% Click Events
    click ImportScheduler "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects"
    click Giveth "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/giveth"
    click Gitcoin "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/gitcoin"
    click RetroFund "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/rf"
    click RetroList "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/retroList"
    click Gardens "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/gardens"
    click RPGF "https://github.com/giveth/devouch-be/tree/develop/src/features/import-projects/rpgf"
    click Shell "https://github.com/giveth/devouch-be/blob/develop/fetch-eas-abi.sh"
    click SubSquid "https://github.com/giveth/devouch-be/blob/develop/src/processor.ts"
    click EventControllers "https://github.com/giveth/devouch-be/tree/develop/src/controllers"
    click Mappings "https://github.com/giveth/devouch-be/blob/develop/src/mappings/attest.ts"
    click GraphQLServer "https://github.com/giveth/devouch-be/blob/develop/schema.graphql"
    click ExtHelpers "https://github.com/giveth/devouch-be/blob/develop/src/server-extension/helper.ts"
    click Migrations "https://github.com/giveth/devouch-be/tree/develop/db/migrations"
    click DbHelpers "https://github.com/giveth/devouch-be/blob/develop/src/helpers/db.ts"
    click ORM "https://github.com/giveth/devouch-be/tree/develop/src/model/generated"
    click Main "https://github.com/giveth/devouch-be/blob/develop/src/main.ts"
    click Tests "https://github.com/giveth/devouch-be/tree/develop/src/test"

    %% Styles
    classDef internal fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef external fill:#ffccaa,stroke:#333,stroke-width:1px
    classDef db fill:#aaaaff,stroke:#333,stroke-width:1px
```
