# openzeppelin/openzeppelin-relayer architecture

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

- Interactive diagram: https://gitdiagram.com/openzeppelin/openzeppelin-relayer
- Repository: https://github.com/openzeppelin/openzeppelin-relayer

## Overview

##### Main Components
- Clients: Represent external systems or SDKs that interact via HTTP APIs.
- API Layer: Shows the exposed endpoints, controllers, and middleware (located in src/api).
- Domain Layer: Captures core business logic including transaction relaying, nonce management, and policy enforcement (see src/domain, src/config, and src/bootstrap).
- Infrastructure: Consists of repositories (data storage and state management, distributed through Redis), job queue handlers (for asynchronous processing in src/jobs), signer services (both local and Vault-based implementations) and provider components (for connecting with blockchain nodes).
- Services Layer: Encompasses transaction services, notification (webhook) modules, metrics/monitoring integrations, and vault services.
- Configuration: Covers configuration files (in config/ and env files) and environment variables, which are used to drive the behavior of the system.
- External Systems: Includes blockchain networks (Solana, EVM), external caches or databases (Redis), external key managers (Vault), monitoring systems (Prometheus/Grafana), and notification endpoints.

##### Relationships & Interactions
- Clients send HTTP requests to the API endpoints.
- The API Layer (routes and controllers) processes requests and delegates responsibility to middleware, which then routes to the Domain Layer.
- The Domain Layer orchestrates the transaction relay logic and policy enforcement using the integrated relayer services.
- The Infrastructure interacts with the Domain, providing persistent storage, job queuing, and external signing capabilities.
- The Services layer handles critical functions like transaction signing (which may refer to both local signing and Vault integrations), fee estimation, and notifications via webhooks.
- Configuration components (config files/environment variables) feed critical parameters to each layer.
- Data flows include requests from clients going through the API, business logic in the Domain communicating with Infrastructure services, while also sending jobs to the queue and interacting with external systems like blockchains and metrics collectors.

##### Architectural Patterns & Design Principles
- Layered architecture: Separation between API, Domain, Infrastructure, and Services.
- Modularity: Each folder under src (controllers, domain, repositories, services, etc.) encapsulates a distinct concern.
- Extensibility: The project is designed to support multiple networks and signing strategies; each can be visualized as separate modules that inject dependencies into the core relayer workflow.
- Asynchronous Processing: The jobs subcomponent works with Redis (as indicated by the docker-compose and external Redis container) to manage asynchronous operations.
- Observability: A dedicated metrics component is integrated which is driven via Prometheus/Grafana.

##### Detailing the Architecture
- The "src/api" directory corresponds to API endpoints and controllers.
- The "src/domain" and "src/models" directories represent the core business logic and data types.
- The "src/repositories" and "src/jobs" directories form the persistence and asynchronous processing layers.
- The "src/services" directory covers various integrations (gas pricing, notification, signer interfaces) and should be visibly separated.
- The "config" and environment (".env") files are critical for configuration management.
- Minor components (like helper scripts from the "helpers" directory or the "docs" and "examples" directories) as annotations if they influence deployment or operational behavior—but keep the primary focus on runtime architecture.

##### Final Recommendations
- Every component has a label that reflects the folder path (e.g., “src/services/signer/evm”).
- Extensibility of modules (for adding new networks or signing mechanisms) by grouping related components together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Clients("Clients"):::clients

    subgraph "OpenZeppelin Relayer"
        subgraph "API Layer"
            A1("Controllers (src/api/controllers)"):::api
            A2("Routes (src/api/routes)"):::api
        end

        subgraph "Domain Layer"
            D1("Core Business Logic (src/domain)"):::domain
            D2("Configuration (src/config)"):::domain
            D3("Bootstrap (src/bootstrap)"):::domain
            D4("Policy & Constants (src/constants)"):::domain
        end

        subgraph "Infrastructure"
            I1("Repositories (src/repositories)"):::infra
            I2("Job Queue (src/jobs)"):::infra
            I3("Signer EVM (src/services/signer/evm)"):::infra
            I4("Signer Solana (src/services/signer/solana)"):::infra
            I5("Provider EVM (src/services/provider/evm)"):::infra
            I6("Provider Solana (src/services/provider/solana)"):::infra
        end

        subgraph "Services Layer"
            S1("Transaction Processing (src/domain/transaction)"):::services
            S2("Transaction Models (src/models/transaction)"):::services
            S3("Notification Service (src/services/notification)"):::services
            S4("Notification Models (src/models/notification)"):::services
            S5("Metrics (src/metrics)"):::services
            S6("Prometheus (cmd/prometheus)"):::services
            S7("Vault Integration (src/services/vault)"):::services
            S8("Vault Signer Config (src/config/config_file/signer)"):::services
        end

        subgraph "Configuration Layer"
            C1("Config Files (config/)"):::config
            C2("Environment (.env.example)"):::config
        end
    end

    %% External Systems
    E1("EVM Blockchain"):::external
    E2("Solana Blockchain"):::external
    E3("Redis"):::external
    E4("Vault External"):::external
    E5("Prometheus/Grafana"):::external
    E6("Notification Endpoint"):::external

    %% Connections between Clients and API Layer
    Clients -->|"HTTP request"| A2
    Clients -->|"HTTP request"| A1

    %% API Layer to Domain Layer
    A1 -->|"forwards request"| D1
    A2 -->|"routes request"| D1

    %% Domain Layer to Infrastructure
    D1 -->|"uses"| I1
    D1 -->|"queues jobs"| I2
    D1 -->|"signs txn via"| I3
    D1 -->|"signs txn via"| I4
    D1 -->|"fetches network data from"| I5
    D1 -->|"fetches network data from"| I6

    %% Domain Layer to Services Layer
    D1 -->|"processes transactions"| S1
    D1 -->|"triggers notifications"| S3

    %% Within Services Layer relationships
    S1 -->|"uses models"| S2
    S3 -->|"formats messages"| S4
    S5 -->|"monitors"| S6
    S7 -- "retrieves keys" --> S8

    %% Configuration feeds into core layers
    C1 ---|"configures"| A1
    C1 ---|"configures"| D1
    C1 ---|"configures"| I1
    C1 ---|"configures"| S1
    C2 ---|"env settings"| D1

    %% Infrastructure External connections
    I5 -->|"connects to"| E1
    I6 -->|"connects to"| E2
    I2 -->|"stores jobs in"| E3

    %% Services External connections
    S7 -->|"integrates with"| E4
    S5 -->|"sends metrics to"| E5
    S3 -->|"calls"| E6

    %% Click Events for API Layer
    click A1 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/api/controllers"
    click A2 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/api/routes"

    %% Click Events for Domain Layer
    click D1 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/domain"
    click D2 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/config"
    click D3 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/bootstrap"
    click D4 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/constants"

    %% Click Events for Infrastructure
    click I1 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/repositories"
    click I2 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/jobs"
    click I3 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/signer/evm"
    click I4 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/signer/solana"
    click I5 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/provider/evm"
    click I6 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/provider/solana"

    %% Click Events for Services Layer
    click S1 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/domain/transaction"
    click S2 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/models/transaction"
    click S3 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/notification"
    click S4 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/models/notification"
    click S5 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/metrics"
    click S6 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/cmd/prometheus"
    click S7 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/services/vault"
    click S8 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/src/config/config_file/signer"

    %% Click Events for Configuration
    click C1 "https://github.com/openzeppelin/openzeppelin-relayer/tree/main/config/"
    click C2 "https://github.com/openzeppelin/openzeppelin-relayer/blob/main/.env.example"

    %% Styles
    classDef clients fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef api fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef domain fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef infra fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef services fill:#D8BFD8,stroke:#333,stroke-width:2px;
    classDef config fill:#F08080,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;
```
