Finalize stack blueprint

Every component in a self-hosted Hyperswitch stack, what it does, and why it exists? So you can decide what to deploy and what to leave out.

---

Stack blueprint

The blueprint exists to answer two questions before you provision anything:

1. Which components does your stack actually need? Several are optional, based on your feature requirements and devops strategy to operate the Hyperswitch stack.

2. Which layers are dedicated to Hyperswitch, and which are shared organization-wide? For example the ingress, egress and content delivery could be commonly provided centrally. If yours are, plug into them instead of duplicating them.

Finalizing your own version of the stack blueprint will be Milestone I of the production certification process.

How to read it?

Components are colored marked based ownership and customization possibility.

Colour	Meaning	How to customize?
Blue	Juspay or open-source software components which are central to operating Hyperswitch stack	Choose the components applicable for your use case. Removing an optional component is a trade-off in features, reliability or Juspay's SLAs. For example: Removing Superposition will disable runtime configuration management for hyperswitch; makes hyperswitch more reliable while rolling out config changes.
Orange	Mandatory tooling the stack depends upon for continuous operations	Can be extended or replaced with alternatives, if needed. For example: Key manager services could be substituted with Hashicorp
Teal	Components you may build and manage yourself	Yours to provide, or to share from an existing organization-level service. For example: You can choose to use your own ingress/ egress at an org level.

Note:

• The networking layer, load balancers, firewalls are not shown in the blue print. Since these are standard for any stack, it will be covered in the final milestone of the production certification.

• Native SDK (Android, iOS, React etc.,) are not included in the blue print, since they are served from specific package manager, the approach to host it could be very flexible as you may need.

---

Entry points

The hyperswitch stack will serve four distinct traffic patterns:

• Users hit the content delivery layer. This is the shoppers loading the checkout experience in a browser or app.

• Merchants hit the API path directly. This is the server-to-server API traffic — payment creation, refunds, status queries; or through the control center which the merchant team will use to configure and operate the payment stack.

• Payment processors sending webhook notification to the hyperswitch endpoint directly. This is for various functionality like updating payment status, disputes etc.,

• Scheduler which takes care of refunds and other Async process.

Content delivery and Object Storage

This is the layer most often already provided at organization level. If you have a CDN as global services within your organization, use them as-is.

Component	Required?	Why it exists
Content Delivery Network	Mandatory	Serves checkout assets from edge locations near the shopper. Caches static assets, results in cheap and faster content delivery.

Object storage

This is where the checkout SDK and its assets live, served to shoppers through the CDN. Small in footprint, but on the critical path for every hosted checkout session.

Component	Required?	Why it exists
SDK Resources	Conditional	Hosts the checkout SDK and its assets, served through the CDN. This may be optional based on your PCI strategy.

Ingress

The front door for all inbound traffic, merchant and shopper alike. It terminates, optionally authenticates and throttles requests before anything reaches the application.

Component	Required?	Why it exists
Envoy	Required	The edge proxy: terminates and routes inbound traffic before it reaches the mesh.
Rate limiter	Required	Protects the payment path from abuse and traffic spikes. Not optional in practice for an internet-facing payments API.
Auth Proxy	Optional	Enforces authentication at the edge rather than in the application. Moving authentication to the edge can help create an isolating agile application changes for a closed user group (CUG) of merchants. This could be very valuable if you would want to deploying changes very frequently across 'm' merchants coming up with 'n' requirements.

Application core

The core application running on Kubernetes: payment processing and its associated functionality. Many services here are optional depending on the use cases you need to serve.

Component	Required?	Why it exists
Istio	Required	Service mesh: maps hostnames and paths to services and applies mesh policy across the core.
OLTP Router	Required	The payment engine — authorisation, capture, refunds, routing decisions. Nothing runs without it.
OLAP Router	Required	Serves read and analytical queries so reporting load never touches the transaction path.
Payment methods	Required	The payment-methods API surface, deployed separately so it scales independently of the router.
Connector Service	Required	Runs processor integrations as their own service, so adding or updating a connector does not mean redeploying the router.
Producer / Consumer	Required	Handles asynchronous work — webhooks, refunds, retries, scheduled payments — off the synchronous request path.
Control Center	Required	The operator dashboard: routing rules, transaction operations, connector configuration, analytics.
Card Vault	Conditional	Tokenises and stores card data. The applicability of the module depends on your PCI strategy.
Decision Engine	Optional	Rule based, Cost-aware and Auth-rate-aware routing decisions to uplift conversion rates and achieve routing business goals
Revenue Recovery	Optional	Recovers failed recurring MIT payments through intelligent retries.
Reconciliation	Optional	Matches processor settlement files against internal records.

Online Transaction Processing (OTLP) storage

The transactional data layer behind the application core. Instances are isolated per service for the critical services to ensure reliability and compliance. The exact instance counts depend on which application core components you include in your deployment.

Component	Required?	Why it exists
PostgreSQL	Required	Transactional store, with separate instances for the OLTP Router, Card Vault, Superposition and Decision Engine. The separation is deliberate — it is what keeps the vault's data isolated from everything else.
Redis	Required	Cache and session tier, with separate instances for the Rate Limiter, OLTP Router, Card Vault, Superposition, Decision Engine and Reconciliation.

Managed services

These are cloud provider or third-party services the Hyperswitch stack depends on, rather than components you deploy yourself.

Component	Required?	Why it exists
Key manager service	Required	Generates and manages the encryption and decryption keys used across the stack — Router, Card vault, Superposition.
Secrets Manager	Required	Holds credentials outside the application cluster, synced in at runtime rather than living in Helm values or Git.
SMTP email service	Required	Sends dashboard signup verification and operational email. Without it, Control Center signup cannot complete.

Management layer

The is component defines how the stack gets provisioned, deployed and configured. These run alongside Hyperswitch rather than serving any payment traffic.

Component	Required?	Why it exists
Terraform/Terragrunt (Devops tool)	Required	Provisions cloud infrastructure with the required provisioning, PCI controls, reliability defaults.
Helm charts (Devops tool)	Required	Packages the application components for deployment.
ArgoCD (Devops tool)	Required	Reconciles the cluster against Git continuously, so what runs is always what is declared.
Superposition	Required	Context-based configuration management — roll out routing rules, retry ladders and feature flags across environments or tenants without redeploying.

Monitoring

The monitoring and observability plane covering every component in the stack. It is how your team — or Juspay, on Tier 1 and Tier 2 — find out the platform is unhealthy before your customers do. It also provides you with the developer telemetry to deepdive and resolve issues.

Component	Required?	Why it exists
OpenTelemetry	Required	Collects metrics, logs and traces from every component in one standard.
Victoria Metrics	Required	Handles metrics.
Loki	Required	Handles logs.
Vector	Required	Ships pod and node logs into Loki.
Grafana	Required	Dashboards over all of the above for monitoring the Infrastructure and Application performance. The Juspay team will also have read access to select metrics to be able to support your team.
Alerts Manager	Conditional	Routes alerts to your on-call system. Skip it only if you already have one. Required if you are on the Tier 1 or Tier 2 plan.

Data processing

The analytics pipeline behind dashboard reporting, insights and ID based search. All events stream out of the transaction path so analytical load never touches live payments.

Component	Required?	Why it exists
Kafka	Required	Streams events out of the transaction path into analytics without adding latency to payments.
ClickHouse	Required	Columnar store powering dashboard analytics and reporting at volume.
Vector	Required	Ships events into the data processing pipeline.
OpenSearch	Optional	Lookup by identifier in the dashboard.
Sessionizer	Optional	Processes data for A/B testing and advanced analytics insights on the dashboard.
Cassandra	Conditional	Backing datastore for the sessioniser.

The data processing layer is not covered by the Terraform modules on any cloud today. ClickHouse, Kafka, OpenSearch and the sessionizer will have to be manually provisioned to enable the hyperswitch control center with dashboard analytics, reporting, ID based search features.

Egress

The single controlled exit from the stack to processors and other external endpoints. Everything outbound goes through here, by design rather than by convention.

Component	Required?	Why it exists
Squid	Required	Forward proxy giving controlled, allow-listed outbound access to processors and external endpoints. In a PCI environment, unrestricted egress from the CDE is not acceptable — this is how you constrain it.