# kyareema01/payment-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/kyareema01/payment-orchestrator
- Repository: https://github.com/kyareema01/payment-orchestrator

## Overview

ZethetaIntern is a payment-orchestration API. A client submits an idempotency-key-protected payment; the API creates a transaction, scores available gateway metrics, selects a gateway, and records the routed state. Gateway webhooks update transactions, while analytics endpoints query gateway volume and success rates. The README also describes a Next.js health dashboard and Stripe, Razorpay, and PayU integrations; their implementation is not present in the supplied tree. Dashed links mark unverified integration points.

Main entry points: [`apps/backend/src/index.ts`](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/index.ts) (Express API), [`apps/backend/src/modules/payment/payment.repository.ts`](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/payment/payment.repository.ts) (Payment repository), [`apps/backend/src/modules/webhook/webhook.service.ts`](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/webhook/webhook.service.ts) (Webhook processor), [`apps/backend/src/modules/router/router.service.ts`](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/router/router.service.ts) (Gateway scorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API ingress"]
  node_api["Express API<br/>[index.ts]"]
  node_idem["Idempotency<br/>[idempotency.ts]"]
end

subgraph group_payments["Payment lifecycle"]
  node_paymentrepo["Payment repository"]
  node_statemachine["State machine"]
  node_database[("MySQL database")]
  node_webhookcontroller["Webhook controller"]
  node_webhookservice["Webhook processor<br/>[webhook.service.ts]"]
end

subgraph group_routing["Gateway routing"]
  node_router["Gateway scorer<br/>[router.service.ts]"]
  node_priorityqueue["Max priority queue<br/>[PriorityQueue.ts]"]
  node_breaker["Circuit breaker<br/>[circuit-breaker.ts]"]
end

subgraph group_insights["Analytics"]
  node_analyticscontroller["Analytics controller"]
  node_analyticsservice["Analytics queries"]
  node_dashboard["Dashboard UI"]
end

node_client(("API client"))
node_gateway(("Payment gateways"))

node_client -->|"submits payments"| node_api
node_api -->|"guards payment route"| node_idem
node_api -->|"creates transaction"| node_paymentrepo
node_api -->|"selects gateway"| node_router
node_api -->|"records routing"| node_paymentrepo
node_router -->|"ranks candidates"| node_priorityqueue
node_paymentrepo -->|"writes and locks"| node_database
node_paymentrepo -->|"validates transitions"| node_statemachine
node_gateway -->|"sends webhook"| node_api
node_api -->|"routes webhook"| node_webhookcontroller
node_webhookcontroller -->|"dispatches status"| node_webhookservice
node_webhookservice -->|"checks event"| node_database
node_webhookservice -->|"updates transaction"| node_paymentrepo
node_client -->|"requests analytics"| node_api
node_api -->|"routes dashboard query"| node_analyticscontroller
node_analyticscontroller -->|"requests metrics"| node_analyticsservice
node_analyticsservice -->|"queries aggregates"| node_database
node_dashboard -.->|"fetches metrics"| node_api
node_router -.->|"routes payment"| node_gateway
node_breaker -.->|"protects calls"| node_gateway

click node_api "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/index.ts"
click node_idem "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/middlewares/idempotency.ts"
click node_paymentrepo "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/payment/payment.repository.ts"
click node_statemachine "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/payment/payment.state-machine.ts"
click node_database "https://github.com/kyareema01/payment-orchestrator/blob/main/migrations/001_initial_schema.sql"
click node_router "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/router/router.service.ts"
click node_priorityqueue "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/dsa/PriorityQueue.ts"
click node_breaker "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/router/circuit-breaker.ts"
click node_webhookcontroller "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/webhook/webhook.controller.ts"
click node_webhookservice "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/webhook/webhook.service.ts"
click node_analyticscontroller "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/analytics/analytics.controller.ts"
click node_analyticsservice "https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/analytics/analytics.service.ts"

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,node_idem,node_client toneBlue
class node_paymentrepo,node_statemachine,node_database,node_webhookcontroller,node_webhookservice toneAmber
class node_router,node_priorityqueue,node_breaker toneMint
class node_analyticscontroller,node_analyticsservice,node_dashboard toneRose
class node_gateway toneIndigo
```

## Components

### API ingress

- [Express API](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/index.ts): `apps/backend/src/index.ts`
- [Idempotency](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/middlewares/idempotency.ts): `apps/backend/src/middlewares/idempotency.ts`

### Payment lifecycle

- [Payment repository](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/payment/payment.repository.ts): `apps/backend/src/modules/payment/payment.repository.ts`
- [State machine](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/payment/payment.state-machine.ts): `apps/backend/src/modules/payment/payment.state-machine.ts`
- [MySQL database](https://github.com/kyareema01/payment-orchestrator/blob/main/migrations/001_initial_schema.sql): `migrations/001_initial_schema.sql`
- [Webhook controller](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/webhook/webhook.controller.ts): `apps/backend/src/modules/webhook/webhook.controller.ts`
- [Webhook processor](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/webhook/webhook.service.ts): `apps/backend/src/modules/webhook/webhook.service.ts`

### Gateway routing

- [Gateway scorer](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/router/router.service.ts): `apps/backend/src/modules/router/router.service.ts`
- [Max priority queue](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/dsa/PriorityQueue.ts): `apps/backend/src/dsa/PriorityQueue.ts`
- [Circuit breaker](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/router/circuit-breaker.ts): `apps/backend/src/modules/router/circuit-breaker.ts`

### Analytics

- [Analytics controller](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/analytics/analytics.controller.ts): `apps/backend/src/modules/analytics/analytics.controller.ts`
- [Analytics queries](https://github.com/kyareema01/payment-orchestrator/blob/main/apps/backend/src/modules/analytics/analytics.service.ts): `apps/backend/src/modules/analytics/analytics.service.ts`
- **Dashboard UI**

### Other components

- **API client**
- **Payment gateways**

## Connections

- API client → Express API: submits payments (evidence: `apps/backend/src/index.ts`)
- Express API → Idempotency: guards payment route (evidence: `apps/backend/src/index.ts`)
- Express API → Payment repository: creates transaction (evidence: `apps/backend/src/index.ts`)
- Express API → Gateway scorer: selects gateway (evidence: `apps/backend/src/index.ts`)
- Express API → Payment repository: records routing (evidence: `apps/backend/src/index.ts`)
- Gateway scorer → Max priority queue: ranks candidates (evidence: `apps/backend/src/modules/router/router.service.ts`)
- Payment repository → MySQL database: writes and locks (evidence: `apps/backend/src/modules/payment/payment.repository.ts`)
- Payment repository → State machine: validates transitions (evidence: `apps/backend/src/modules/payment/payment.repository.ts`)
- Payment gateways → Express API: sends webhook (evidence: `apps/backend/src/index.ts`)
- Express API → Webhook controller: routes webhook (evidence: `apps/backend/src/index.ts`)
- Webhook controller → Webhook processor: dispatches status (evidence: `apps/backend/src/modules/webhook/webhook.controller.ts`)
- Webhook processor → MySQL database: checks event (evidence: `apps/backend/src/modules/webhook/webhook.service.ts`)
- Webhook processor → Payment repository: updates transaction (evidence: `apps/backend/src/modules/webhook/webhook.service.ts`)
- API client → Express API: requests analytics (evidence: `apps/backend/src/index.ts`)
- Express API → Analytics controller: routes dashboard query (evidence: `apps/backend/src/index.ts`)
- Analytics controller → Analytics queries: requests metrics (evidence: `apps/backend/src/modules/analytics/analytics.controller.ts`)
- Analytics queries → MySQL database: queries aggregates (evidence: `apps/backend/src/modules/analytics/analytics.service.ts`)
- Dashboard UI → Express API: fetches metrics (evidence: `README.md`)
- Gateway scorer → Payment gateways: routes payment (evidence: `README.md`)
- Circuit breaker → Payment gateways: protects calls