# juspay/hyperswitch architecture

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

- Interactive diagram: https://gitdiagram.com/juspay/hyperswitch
- Repository: https://github.com/juspay/hyperswitch
- Video tour (about a minute): https://gitdiagram.com/juspay/hyperswitch/video

## Overview

Hyperswitch is a modular payments infrastructure stack. Its principal workflow is a merchant or client initiating a payment through the router, which processes it and can route it to a configured payment processor; related product capabilities include payment methods and vaulting, intelligent routing, revenue recovery, and analytics. The tree and README establish these product areas, but most runtime implementation excerpts are absent, so uncertain internal links are dashed and left uncited rather than presented as verified calls.

Main entry points: [`crates/router/src/core/payments`](https://github.com/juspay/hyperswitch/tree/main/crates/router/src/core/payments) (Payment orchestration), [`crates/router/src/routes.rs`](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes.rs) (API routes), [`crates/hyperswitch_connectors/src/connectors`](https://github.com/juspay/hyperswitch/tree/main/crates/hyperswitch_connectors/src/connectors) (Payment connectors), [`crates/router/src/routes/payments.rs`](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/payments.rs) (Payment endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api_routes["API routes<br/>[routes.rs]"]
  node_app_routes["App routes<br/>[app.rs]"]
  node_payment_routes["Payment endpoints<br/>[payments.rs]"]
end

subgraph group_payments["Payment processing"]
  node_payment_core["Payment orchestration"]
  node_domain_models["Payment domain<br/>[router_data.rs]"]
  node_routing["Intelligent routing"]
end

subgraph group_connectivity["Processors and storage"]
  node_connectors["Payment connectors"]
  node_connector_template["Connector template<br/>[mod.rs]"]
  node_storage["Storage interface<br/>[storage.rs]"]
  node_storage_impl[("Storage backend<br/>[kv_router_store.rs]")]
  node_processors(("External processors"))
end

subgraph group_operations["Payment capabilities"]
  node_payment_methods["Payment methods<br/>[controller.rs]"]
  node_vault["File storage<br/>[file_storage.rs]"]
  node_revenue_recovery["Revenue recovery"]
  node_offer_routes["Offer endpoints<br/>[offer_engine.rs]"]
  node_offer_core["Offer engine<br/>[offer_engine.rs]"]
  node_offer_notify["Offer notifications<br/>[notify.rs]"]
end

subgraph group_insights["Analytics and observability"]
  node_analytics_api["Analytics endpoints<br/>[analytics.rs]"]
  node_analytics_query["Analytics queries<br/>[query.rs]"]
  node_analytics_models["Analytics models<br/>[analytics.rs]"]
  node_logs["Structured logging<br/>[storage.rs]"]
end

node_merchant(("Merchant client"))

node_merchant -.->|"sends requests"| node_api_routes
node_api_routes -->|"routes requests"| node_payment_routes
node_payment_routes -.->|"dispatches payments"| node_payment_core
node_payment_core -.->|"uses payment data"| node_domain_models
node_payment_core -.->|"selects route"| node_routing
node_routing -.->|"dispatches payment"| node_connectors
node_connectors -.->|"sends transactions"| node_processors
node_payment_core -.->|"persists payment"| node_storage
node_storage -.->|"uses backend"| node_storage_impl
node_payment_core -.->|"uses payment methods"| node_payment_methods
node_payment_methods -.->|"stores credentials"| node_vault
node_payment_core -.->|"supports retries"| node_revenue_recovery
node_api_routes -.->|"registers routes"| node_offer_routes
node_offer_routes -->|"dispatches offer requests"| node_offer_core
node_offer_core -.->|"schedules notifications"| node_offer_notify
node_api_routes -.->|"registers analytics"| node_analytics_api
node_analytics_api -.->|"queries analytics"| node_analytics_query
node_analytics_query -.->|"uses request models"| node_analytics_models
node_api_routes -.->|"records request context"| node_logs
node_connectors -.->|"follows connector pattern"| node_connector_template

click node_api_routes "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes.rs"
click node_app_routes "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/app.rs"
click node_payment_routes "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/payments.rs"
click node_payment_core "https://github.com/juspay/hyperswitch/tree/main/crates/router/src/core/payments"
click node_domain_models "https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_domain_models/src/router_data.rs"
click node_routing "https://github.com/juspay/hyperswitch/tree/main/crates/router/src/core/routing"
click node_connectors "https://github.com/juspay/hyperswitch/tree/main/crates/hyperswitch_connectors/src/connectors"
click node_connector_template "https://github.com/juspay/hyperswitch/blob/main/connector-template/mod.rs"
click node_storage "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/types/storage.rs"
click node_storage_impl "https://github.com/juspay/hyperswitch/blob/main/crates/storage_impl/src/kv_router_store.rs"
click node_payment_methods "https://github.com/juspay/hyperswitch/blob/main/crates/payment_methods/src/controller.rs"
click node_vault "https://github.com/juspay/hyperswitch/blob/main/crates/external_services/src/file_storage.rs"
click node_revenue_recovery "https://github.com/juspay/hyperswitch/blob/main/crates/subscriptions/src/core/billing_processor_handler.rs"
click node_offer_routes "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/offer_engine.rs"
click node_offer_core "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/core/offer_engine.rs"
click node_offer_notify "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/core/offer_engine/notify.rs"
click node_analytics_api "https://github.com/juspay/hyperswitch/blob/main/crates/router/src/analytics.rs"
click node_analytics_query "https://github.com/juspay/hyperswitch/blob/main/crates/analytics/src/query.rs"
click node_analytics_models "https://github.com/juspay/hyperswitch/blob/main/crates/api_models/src/analytics.rs"
click node_logs "https://github.com/juspay/hyperswitch/blob/main/crates/router_env/src/logger/storage.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_routes,node_app_routes,node_payment_routes,node_merchant toneBlue
class node_payment_core,node_domain_models,node_routing toneAmber
class node_connectors,node_connector_template,node_storage,node_storage_impl,node_processors toneMint
class node_payment_methods,node_vault,node_revenue_recovery,node_offer_routes,node_offer_core,node_offer_notify toneRose
class node_analytics_api,node_analytics_query,node_analytics_models,node_logs toneIndigo
```

## Components

### API and orchestration

- [API routes](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes.rs): `crates/router/src/routes.rs`
- [App routes](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/app.rs): `crates/router/src/routes/app.rs`
- [Payment endpoints](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/payments.rs): `crates/router/src/routes/payments.rs`

### Payment processing

- [Payment orchestration](https://github.com/juspay/hyperswitch/tree/main/crates/router/src/core/payments): `crates/router/src/core/payments`
- [Payment domain](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_domain_models/src/router_data.rs): `crates/hyperswitch_domain_models/src/router_data.rs`
- [Intelligent routing](https://github.com/juspay/hyperswitch/tree/main/crates/router/src/core/routing): `crates/router/src/core/routing`

### Processors and storage

- [Payment connectors](https://github.com/juspay/hyperswitch/tree/main/crates/hyperswitch_connectors/src/connectors): `crates/hyperswitch_connectors/src/connectors`
- [Connector template](https://github.com/juspay/hyperswitch/blob/main/connector-template/mod.rs): `connector-template/mod.rs`
- [Storage interface](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/types/storage.rs): `crates/router/src/types/storage.rs`
- [Storage backend](https://github.com/juspay/hyperswitch/blob/main/crates/storage_impl/src/kv_router_store.rs): `crates/storage_impl/src/kv_router_store.rs`
- **External processors**

### Payment capabilities

- [Payment methods](https://github.com/juspay/hyperswitch/blob/main/crates/payment_methods/src/controller.rs): `crates/payment_methods/src/controller.rs`
- [File storage](https://github.com/juspay/hyperswitch/blob/main/crates/external_services/src/file_storage.rs): `crates/external_services/src/file_storage.rs`
- [Revenue recovery](https://github.com/juspay/hyperswitch/blob/main/crates/subscriptions/src/core/billing_processor_handler.rs): `crates/subscriptions/src/core/billing_processor_handler.rs`
- [Offer endpoints](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/routes/offer_engine.rs): `crates/router/src/routes/offer_engine.rs`
- [Offer engine](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/core/offer_engine.rs): `crates/router/src/core/offer_engine.rs`
- [Offer notifications](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/core/offer_engine/notify.rs): `crates/router/src/core/offer_engine/notify.rs`

### Analytics and observability

- [Analytics endpoints](https://github.com/juspay/hyperswitch/blob/main/crates/router/src/analytics.rs): `crates/router/src/analytics.rs`
- [Analytics queries](https://github.com/juspay/hyperswitch/blob/main/crates/analytics/src/query.rs): `crates/analytics/src/query.rs`
- [Analytics models](https://github.com/juspay/hyperswitch/blob/main/crates/api_models/src/analytics.rs): `crates/api_models/src/analytics.rs`
- [Structured logging](https://github.com/juspay/hyperswitch/blob/main/crates/router_env/src/logger/storage.rs): `crates/router_env/src/logger/storage.rs`

### Other components

- **Merchant client**

## Connections

- Merchant client → API routes: sends requests
- API routes → Payment endpoints: routes requests (evidence: `crates/router/src/routes.rs`)
- Payment endpoints → Payment orchestration: dispatches payments
- Payment orchestration → Payment domain: uses payment data
- Payment orchestration → Intelligent routing: selects route
- Intelligent routing → Payment connectors: dispatches payment
- Payment connectors → External processors: sends transactions
- Payment orchestration → Storage interface: persists payment
- Storage interface → Storage backend: uses backend
- Payment orchestration → Payment methods: uses payment methods
- Payment methods → File storage: stores credentials
- Payment orchestration → Revenue recovery: supports retries
- API routes → Offer endpoints: registers routes (evidence: `crates/router/src/routes.rs`)
- Offer endpoints → Offer engine: dispatches offer requests (evidence: `crates/router/src/routes/offer_engine.rs`)
- Offer engine → Offer notifications: schedules notifications (evidence: `crates/router/src/core/offer_engine.rs`)
- API routes → Analytics endpoints: registers analytics (evidence: `crates/router/src/routes.rs`)
- Analytics endpoints → Analytics queries: queries analytics
- Analytics queries → Analytics models: uses request models
- API routes → Structured logging: records request context
- Payment connectors → Connector template: follows connector pattern