# ayanooxd/razorpay-api architecture

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

- Interactive diagram: https://gitdiagram.com/ayanooxd/razorpay-api
- Repository: https://github.com/ayanooxd/razorpay-api

## Overview

1. **Overall shape**
   - This is a single-binary Go service, with most of the logic in `autorzp.go`.
   - It exposes an HTTP API, drives a remote Razorpay checkout flow, and reports the result as JSON.
   - The rest of the repo is mostly configuration, packaging, and tests.

2. **Runtime boundary**
   - The server listens on `PORT` (default `7070`).
   - It provides two public endpoints: `/health` for liveness checks and `/razorpay/cc=...` for the card-check workflow.
   - The service is designed to run standalone in a container or on Railway.

3. **Primary request flow**
   - A client sends a card payload in the URL path as `cc|mm|yy|cvv`.
   - The handler validates the request, acquires capacity from a concurrency limiter, and then starts the Razorpay check process.
   - The final response is normalized into a small JSON status object, such as `approved`, `declined`, `charged`, or `error`.

4. **Razorpay interaction subsystem**
   - The core business logic is the browser-like HTTP interaction with a real Razorpay payment page.
   - The service appears to emulate enough client behavior to get a bank/WAF response back from Razorpay rather than simply doing a local validation.
   - Response handling includes parsing upstream responses and interpreting block/decline/approval outcomes.

5. **Proxy and site inputs**
   - `px.txt` supplies proxy endpoints, optionally with credentials, and `sites.txt` supplies Razorpay payment-page URLs.
   - These files are external data inputs, not code, and they influence how outbound requests are routed and which checkout pages are exercised.
   - `proxy_file` and `sites_file` env vars let those paths be swapped without changing the binary.

6. **State and logging**
   - `live.txt` is the runtime output file where approved/charged cards are logged.
   - This is an append-style side effect rather than a database-backed system.
   - Because it is file-based, persistence is simple but local to the filesystem or mounted volume.

7. **Concurrency and backpressure**
   - The service uses a semaphore-like limiter controlled by `MAX_CONCURRENT` (default `120`).
   - If all slots are busy, new requests wait up to a bounded timeout and then receive `503` instead of hanging.
   - This is the main load-shedding boundary in the architecture.

8. **Networking and resilience concerns**
   - The README indicates the server has explicit protections for slow requests, retries, graceful shutdown, and panic recovery.
   - Upstream content encoding is handled explicitly, which matters because the service consumes compressed responses from remote systems.
   - The request lifecycle is therefore: accept HTTP request → constrain concurrency → call remote upstreams via proxy/site selection → parse response → return JSON.

9. **Security and deployability boundaries**
   - The service is packaged for container deployment via a multi-stage `Dockerfile`.
   - `railway.json` wires the container to Railway’s deployment model and healthcheck behavior.
   - `HEALTHCHECK` in the container and `/health` in the app are the operational contract for orchestrators.

10. **Build and test structure**
   - `Makefile` provides the main local workflows: build, run, test, lint, coverage, and Docker tasks.
   - `autorzp_test.go` focuses on helper behavior and regression-prone logic, including the failure modes called out in the README.
   - `go.mod` indicates Go 1.22+ as the runtime/toolchain baseline.

11. **Architectural summary for a diagram**
   - Draw this as a thin HTTP front door, a central request processor, and three main dependency streams: proxy list, site list, and live-results file.
   - The only external network dependency of interest is Razorpay, reached through rotating proxies.
   - The key operational controls are health checks, concurrency limiting, and graceful shutdown.

Main entry points: [`autorzp.go`](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go) (autorzp.go), [`px.txt`](https://github.com/ayanooxd/razorpay-api/blob/main/px.txt) (px.txt), [`sites.txt`](https://github.com/ayanooxd/razorpay-api/blob/main/sites.txt) (sites.txt), [`live.txt`](https://github.com/ayanooxd/razorpay-api/blob/main/live.txt) (live.txt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_autorzp["autorzp.go<br/>Go service<br/>[autorzp.go]"]
  node_http_api["HTTP API<br/>routes<br/>[autorzp.go]"]
  node_health_check(("Health check<br/>endpoint<br/>[autorzp.go]"))
  node_card_check["Card check<br/>workflow<br/>[autorzp.go]"]
  node_limiter{{"Limiter<br/>concurrency guard<br/>[autorzp.go]"}}
  node_checker["Razorpay flow<br/>browser-like client<br/>[autorzp.go]"]
  node_response_norm["Result JSON<br/>response mapper<br/>[autorzp.go]"]
  node_retry_shutdown{{"Resilience<br/>ops logic<br/>[autorzp.go]"}}
  node_env_config["Env vars<br/>runtime config<br/>[autorzp.go]"]
  node_razorpay_ext[("Razorpay<br/>external payment site")]
end

subgraph group_data["Data"]
  node_proxy_file["px.txt<br/>proxy list<br/>[px.txt]"]
  node_sites_file["sites.txt<br/>site list<br/>[sites.txt]"]
  node_live_file["live.txt<br/>results log<br/>[live.txt]"]
end

subgraph group_delivery["Delivery"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_railway["railway.json<br/>deploy config<br/>[railway.json]"]
  node_makefile["Makefile<br/>workflow"]
end

node_autorzp -->|"serves"| node_http_api
node_http_api -->|"GET /health"| node_health_check
node_http_api -->|"GET /razorpay/cc=..."| node_card_check
node_card_check -->|"acquires slot"| node_limiter
node_card_check -->|"starts flow"| node_checker
node_checker -->|"uses proxies"| node_proxy_file
node_checker -->|"selects site"| node_sites_file
node_checker -->|"calls upstream"| node_razorpay_ext
node_checker -->|"interprets outcome"| node_response_norm
node_response_norm -->|"logs success"| node_live_file
node_card_check -->|"protected by"| node_retry_shutdown
node_autorzp -->|"reads config"| node_env_config
node_autorzp -->|"packaged by"| node_dockerfile
node_autorzp -->|"deploys on"| node_railway
node_autorzp -->|"developed with"| node_makefile
node_autorzp -->|"depends on"| node_razorpay_ext

click node_autorzp "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_http_api "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_health_check "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_card_check "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_limiter "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_checker "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_response_norm "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_retry_shutdown "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_proxy_file "https://github.com/ayanooxd/razorpay-api/blob/main/px.txt"
click node_sites_file "https://github.com/ayanooxd/razorpay-api/blob/main/sites.txt"
click node_live_file "https://github.com/ayanooxd/razorpay-api/blob/main/live.txt"
click node_env_config "https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go"
click node_dockerfile "https://github.com/ayanooxd/razorpay-api/tree/main/Dockerfile"
click node_railway "https://github.com/ayanooxd/razorpay-api/blob/main/railway.json"
click node_makefile "https://github.com/ayanooxd/razorpay-api/tree/main/Makefile"

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_autorzp,node_http_api,node_health_check,node_card_check,node_limiter,node_checker,node_response_norm,node_retry_shutdown,node_env_config,node_razorpay_ext toneBlue
class node_proxy_file,node_sites_file,node_live_file toneAmber
class node_dockerfile,node_railway,node_makefile toneMint
```

## Components

### Runtime

Live request-processing and operational boundary

- [autorzp.go](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): Go service · Single-binary HTTP server and request orchestrator · `autorzp.go`
- [HTTP API](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): routes · Public endpoints for health checks and card-check requests · `autorzp.go`
- [Health check](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): endpoint · Liveness endpoint used by orchestrators · `autorzp.go`
- [Card check](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): workflow · Parses the cc|mm|yy|cvv request and starts the check flow · `autorzp.go`
- [Limiter](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): concurrency guard · Bounds in-flight requests and sheds load on timeout · `autorzp.go`
- [Razorpay flow](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): browser-like client · Drives the remote checkout interaction and interprets outcomes · `autorzp.go`
- [Result JSON](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): response mapper · Normalizes outcomes such as approved, declined, charged, or error · `autorzp.go`
- [Resilience](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): ops logic · Handles retries, graceful shutdown, and panic recovery · `autorzp.go`
- [Env vars](https://github.com/ayanooxd/razorpay-api/blob/main/autorzp.go): runtime config · PORT, MAX_CONCURRENT, proxy_file, sites_file, and related settings · `autorzp.go`
- **Razorpay**: external payment site · Upstream payment flow reached through rotating proxies

### Data

External input and output files used by the service

- [px.txt](https://github.com/ayanooxd/razorpay-api/blob/main/px.txt): proxy list · Proxy endpoints and credentials used for outbound routing · `px.txt`
- [sites.txt](https://github.com/ayanooxd/razorpay-api/blob/main/sites.txt): site list · Razorpay payment-page URLs exercised by the checker · `sites.txt`
- [live.txt](https://github.com/ayanooxd/razorpay-api/blob/main/live.txt): results log · Append-only log of approved or charged cards · `live.txt`

### Delivery

Build and deployment surface

- [Dockerfile](https://github.com/ayanooxd/razorpay-api/tree/main/Dockerfile): container build · Multi-stage container packaging and healthcheck wiring · `Dockerfile`
- [railway.json](https://github.com/ayanooxd/razorpay-api/blob/main/railway.json): deploy config · Railway deployment and healthcheck integration · `railway.json`
- [Makefile](https://github.com/ayanooxd/razorpay-api/tree/main/Makefile): workflow · Local build, run, test, lint, coverage, and Docker tasks · `Makefile`

## Connections

- autorzp.go → HTTP API: serves · Main binary exposes the HTTP surface
- HTTP API → Health check: GET /health · Operational liveness endpoint
- HTTP API → Card check: GET /razorpay/cc=... · Primary card-check request path
- Card check → Limiter: acquires slot · Bounds concurrent request processing
- Card check → Razorpay flow: starts flow · Hands validated request into upstream checkout logic
- Razorpay flow → px.txt: uses proxies · Rotates outbound routing through configured proxies
- Razorpay flow → sites.txt: selects site · Chooses a payment-page URL to exercise
- Razorpay flow → Razorpay: calls upstream · Performs remote payment-page interaction
- Razorpay flow → Result JSON: interprets outcome · Converts upstream responses into service statuses
- Result JSON → live.txt: logs success · Appends approved or charged results to disk
- Card check → Resilience: protected by · Request lifecycle includes retries and recovery safeguards
- autorzp.go → Env vars: reads config · Uses environment variables for port, limits, and file paths
- autorzp.go → Dockerfile: packaged by · Built into a container image for deployment
- autorzp.go → railway.json: deploys on · Operationalized through Railway settings
- autorzp.go → Makefile: developed with · Local workflow entrypoint for build and test tasks
- autorzp.go → Razorpay: depends on · Core business logic centers on the external checkout flow
