# bobbercheng/hyperswitch architecture

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

- Interactive diagram: https://gitdiagram.com/bobbercheng/hyperswitch
- Repository: https://github.com/bobbercheng/hyperswitch

## Overview

##### Main Components
- Backend Server: The heart of the project is the Hyperswitch backend. Its core logic is implemented in Rust (as evidenced by Cargo.toml, rustfmt.toml, and various Rust modules such as connector-template).
- Connectors/Plugins: The presence of a “connector-template” directory and helper scripts (e.g., add_connector.md) indicates an extensible/plugin-based connector system. These allow custom payment flows for different PSPs.
- Configuration and Migrations: A robust configuration directory (config/) with multiple deployment-specific TOML files, along with migration scripts (found in v2_migrations and v2_compatible_migrations), suggests a well-managed database schema evolution and rich configuration management.
- Infrastructure & Deployment: Dockerfiles, Docker Compose files, and AWS scripts hint at containerized deployments with different environments (development, production, sandbox). External scripts for managing local setup (e.g., INSTALL_dependencies.sh) and cloud deployments (aws/) are also included.
- Database and Caching: Although not explicitly mentioned in all configuration files, hints like redis.conf and references to migration scripts strongly suggest a managed database (likely PostgreSQL) and caching mechanisms with Redis.
- Monitoring & Observability: With directories like "monitoring" and configurations for Grafana, Prometheus, Loki, and Open Telemetry (otel-collector.yaml) there is a clear focus on logging, monitoring, and observability services.
- External Services and APIs: The README and docker compose outputs mention endpoints for health-checks, control center UI, and even hosted demos. There’s also integration with external payment orchestration flows as described in the introductory text.

##### Relationships and Interactions
- The backend orchestrates payment flows, managing the “connectors” to various PSPs (via the connector-template) and uses its configuration to determine routing, retries, and fallback mechanisms.
- API calls from the SDK (frontend) and the Control Center interact with the backend; these components (though maintained in separate repos) are closely coupled.
- The backend interacts with the database (handled via migration scripts and SQL files) and caching systems like Redis.
- Monitoring components ingest logs and metrics from the backend via exporters configured in the monitoring and docker directories.
- Infrastructure components (docker-compose, AWS scripts) sit outside the core business logic but ensure that all components are deployed and networked properly.

##### Architectural Patterns & Design Principles
- Modular/Plugin Architecture: The design based on connector-template and pluggable modules for different payment methods.
- Configuration Driven: A heavy reliance on TOML and other configuration files indicates that behavior (deployment-specific, feature toggling) is carefully separated from code.
- Containerization: Use of Docker and Docker Compose for local and production deployments, facilitating microservices-like encapsulation of different components.
- Observability & Resilience: Emphasis on monitoring (Grafana, Prometheus, etc.) and integration testing (see integration test TOML files) underlines a production-grade and highly resilient architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interfaces"
        sdk["SDK/Frontend"]:::external
        control["Control Center"]:::external
    end

    subgraph "Core Engine"
        backend["Hyperswitch Backend"]:::backend
    end

    subgraph "Modules"
        connectors["Connectors/Plugins"]:::plugin
        config["Configuration & Migrations"]:::config
    end

    subgraph "Data & Cache"
        postgres["PostgreSQL Database"]:::database
        redis["Redis Cache"]:::database
    end

    subgraph "Observability"
        monitor["Monitoring & Observability"]:::monitor
    end

    subgraph "API Contracts"
        externalApi["External Services & APIs"]:::external
    end

    subgraph "Deployment"
        infra["Infrastructure & Deployment"]:::infra
    end

    %% Connections between layers
    sdk -->|"calls"| backend
    control -->|"calls"| backend
    backend -->|"invokes"| connectors
    backend -->|"loads"| config
    backend -->|"queries"| postgres
    backend -->|"caches"| redis
    backend -->|"sends metrics"| monitor
    backend -->|"exposes"| externalApi

    infra -->|"hosts"| backend
    infra -->|"hosts"| postgres
    infra -->|"hosts"| redis
    infra -->|"hosts"| monitor
    infra -->|"hosts"| externalApi

    %% Class definitions for colors and styles
    classDef external fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef plugin fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef config fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef database fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef monitor fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click backend "https://github.com/bobbercheng/hyperswitch/blob/main/Cargo.toml"
    click connectors "https://github.com/bobbercheng/hyperswitch/tree/main/connector-template/"
    click config "https://github.com/bobbercheng/hyperswitch/tree/main/config/"
    click infra "https://github.com/bobbercheng/hyperswitch/tree/main/Dockerfile"
    click postgres "https://github.com/bobbercheng/hyperswitch/tree/main/v2_migrations/"
    click redis "https://github.com/bobbercheng/hyperswitch/blob/main/config/redis.conf"
    click monitor "https://github.com/bobbercheng/hyperswitch/tree/main/monitoring/"
    click externalApi "https://github.com/bobbercheng/hyperswitch/tree/main/proto/"
```
