# raunakgurud09/payments architecture

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

- Interactive diagram: https://gitdiagram.com/raunakgurud09/payments
- Repository: https://github.com/raunakgurud09/payments

## Overview

This is a **two-tier full-stack demo app** showing **Razorpay payment gateway integration**:
- **Frontend**: React + TypeScript (Vite) UI for selecting products/amount and initiating payment.
- **Backend**: Node.js + TypeScript API (very likely Express) that talks to **Razorpay APIs** and persists **Order** data via a small DB layer.
- **External**: Razorpay Checkout + Razorpay Orders/Payments APIs.

##### Frontend (`client/`)
Key architecture signals from the tree:
- `client/src/pages/Products.tsx`, `Success.tsx`, `Failure.tsx`
→ page-level routing/views (even if not using react-router, these are “screens”).
- `client/src/components/Card.tsx`
→ reusable UI components for product display.
- `client/src/api/products.json`
- `vite.config.ts`, `tailwind.config.js`, `postcss.config.js`

- Collect amount / choose product
- Call backend to create payment/order
- Invoke Razorpay Checkout (client-side integration)
- Handle redirect to Success/Failure

##### Backend (`server/`)
Key architecture signals:
- `server/src/index.ts` + `server/src/app.ts`
→ entrypoint and app composition (Express-style bootstrapping, middleware, routes).
- `server/src/routes/*`
- `payment.routes.ts`
- `healthcheck.routes.ts`
→ HTTP route modules; represent as API surface.
- `server/src/controllers/payment/*` and `controllers/healthcheck.controllers.ts`
→ request handling / orchestration logic.
- `server/src/model/order.ts`
- `server/src/db/index.ts`
- `.env.sample` includes `RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`
→ critical security boundary: secrets live **only on server**.

Backend responsibilities to represent:
- Create Razorpay Order (server-to-Razorpay)
- Verify payment (signature verification typically server-side)
- Persist order/payment state
- Provide healthcheck endpoint

##### External system
- Razorpay APIs (Orders/Payments)
- Razorpay Checkout (hosted/payment UI invoked from browser)

Shows: Browser (React app), Node API server, DB, Razorpay.

Shows: User → React → Backend → Razorpay → React → Backend → DB.

Shows internal server structure: Routes → Controllers → Services (if present) → Razorpay client + DB adapter → Order model.

##### Node API → React: returns data needed to open Checkout
- e.g., `order_id`, `key_id`, `amount`, etc.
##### React → Razorpay Checkout (JS): opens checkout widget (external UI)
7. **Razorpay Checkout → React**: returns `payment_id`, `order_id`, `signature` (or error/cancel)

##### Supporting flow
- **React / Monitor → Node API**: `GET /healthcheck` (from `healthcheck.routes.ts`)

If your backend uses webhooks (not visible in the tree), add:
- **Razorpay → Node API**: webhook events (payment.captured, payment.failed)

##### Important architectural patterns to highlight (specific to this repo)
- **Separation of concerns in backend**: `routes/` → `controllers/` → `db/` + `model/`
- **Frontend UI composition**: pages vs components, with local static `products.json`
- **Security pattern**: Razorpay secret never leaves server; verification happens server-side
- **State model**: “Order” is the core domain entity persisted via `db/index.ts`

##### “Don’t overthink it” checklist (separate into as many components as possible)
To maximize detail without inventing things:
- In frontend: separate **Pages**, **Components**, **Static Catalog**, **Razorpay Checkout JS**
- In backend: separate **Routes**, **Controllers**, **Order Model**, **DB Adapter**, **Razorpay API Client**, **Config/Constants**
- External: split Razorpay into **Checkout UI** and **REST APIs**

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% View 1: C4 L2 Containers
    %% =========================
    subgraph V1["View 1 — Container Diagram (C4 L2)"]
        direction TB

        subgraph TBClient["Trust Boundary — Browser (Client)"]
            direction TB
            User["User"]:::person

            subgraph ReactSPA["React SPA (Vite + TypeScript)"]
                direction TB
                FE_App["App Shell"]:::frontend
                FE_Pages["Pages: Products / Success / Failure"]:::frontend
                FE_Card["UI Component: Card"]:::frontend
                FE_Catalog["Local Static Catalog: products.json"]:::data
                FE_Const["Frontend Constants / Config"]:::config
            end

            RP_Checkout["Razorpay Checkout (JS widget)"]:::externalui
        end

        subgraph TBServer["Trust Boundary — Server (Backend)"]
            direction TB
            BE_API["Node.js API (TypeScript, Express-like)"]:::backend
            BE_Routes["HTTP Routes: /payment/*, /healthcheck"]:::backend
            BE_Controllers["Controllers: payment, healthcheck"]:::backend
            BE_Config["Backend Constants / Config"]:::config
            BE_Secrets["Environment Variables / Secrets (Razorpay keys)"]:::secrets
            DB[(Database: Orders)]:::db
        end

        subgraph TBThird["Trust Boundary — 3rd-Party (Razorpay)"]
            direction TB
            RP_APIs["Razorpay Orders/Payments APIs"]:::external
        end

        %% Container relationships
        User -->|"selectProduct/amount"| FE_Pages
        FE_Pages -->|"render"| FE_Card
        FE_Pages -->|"readLocalCatalog"| FE_Catalog

        FE_App -->|"uses"| FE_Const
        FE_App -->|"callsAPI"| BE_API

        BE_API -->|"mounts"| BE_Routes
        BE_Routes -->|"dispatches"| BE_Controllers
        BE_Controllers -->|"uses"| BE_Config
        BE_Controllers -->|"reads"| BE_Secrets
        BE_Controllers -->|"persistOrderState"| DB

        BE_Controllers -->|"createOrder"| RP_APIs
        FE_App -->|"openCheckout"| RP_Checkout
        RP_Checkout -->|"processPayment"| RP_APIs
    end

    %% =====================================
    %% View 2: Payment Flow (Sequence-style)
    %% =====================================
    subgraph V2["View 2 — Payment Flow (Sequence)"]
        direction TB

        S1["1. User chooses product/amount (Products page)"]:::step
        S2["2. React → API: POST /payment/create-order {amount,currency,...}"]:::step
        S3["3. API → Razorpay: Create Order (uses key_secret server-side)"]:::step
        S4["4. Razorpay → API: order_id + order details"]:::step
        S5["5. API → React: key_id + order_id + amount"]:::step
        S6["6. React → Razorpay Checkout: open widget"]:::step
        S7["7. Checkout → React: payment_id + order_id + signature (or error/cancel)"]:::step
        S8["8. React → API: POST /payment/verify {payment_id,order_id,signature}"]:::step
        S9["9. API: verifySignature + update/persist Order status"]:::step
        S10["10. API → React: success/failure → route to Success/Failure page"]:::step

        HF["Supporting: GET /healthcheck"]:::step

        %% Sequence connections (vertical)
        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10

        %% Tie steps to containers (dotted)
        S1 -.-> FE_Pages
        S2 -.-> BE_Routes
        S3 -.-> RP_APIs
        S6 -.-> RP_Checkout
        S9 -.-> DB
        HF -.-> BE_Routes
    end

    %% ==================================
    %% View 3: Backend Components (L3-ish)
    %% ==================================
    subgraph V3["View 3 — Backend Component Diagram (C4 L3)"]
        direction TB

        BE_Index["server entrypoint (index.ts)"]:::backend
        BE_App["app composition (app.ts)"]:::backend

        subgraph BE_Routing["Routing Layer (routes/)"]
            direction TB
            R_Payment["payment.routes.ts"]:::backend
            R_Health["healthcheck.routes.ts"]:::backend
        end

        subgraph BE_Control["Controller Layer (controllers/)"]
            direction TB
            C_Payment["payment controller(s)"]:::backend
            C_Health["healthcheck controller"]:::backend
        end

        subgraph BE_Domain["Domain + Persistence"]
            direction TB
            M_Order["Order Model / Entity (order.ts)"]:::model
            P_DB["DB Adapter (db/index.ts)"]:::db
        end

        subgraph BE_Integrations["Integrations + Config"]
            direction TB
            K_Const["constants (Razorpay config, etc.)"]:::config
            K_Env[".env (Razorpay keys)"]:::secrets
            I_Razor["Razorpay API Client (SDK/HTTP)"]:::external
        end

        %% Wiring
        BE_Index -->|"bootstraps"| BE_App
        BE_App -->|"mountsRoutes"| R_Payment
        BE_App -->|"mountsRoutes"| R_Health

        R_Payment -->|"calls"| C_Payment
        R_Health -->|"calls"| C_Health

        C_Payment -->|"createOrder/verify"| I_Razor
        C_Payment -->|"uses"| K_Const
        C_Payment -->|"reads"| K_Env
        C_Payment -->|"read/write"| P_DB
        P_DB -->|"stores"| M_Order

        C_Health -->|"returnsStatus"| BE_App
    end

    %% =========================
    %% Click events (mapped paths)
    %% =========================
    click FE_App "https://github.com/raunakgurud09/payments/blob/main/client/src/App.tsx"
    click FE_App "https://github.com/raunakgurud09/payments/blob/main/client/src/main.tsx"
    click FE_Pages "https://github.com/raunakgurud09/payments/blob/main/client/src/pages/Products.tsx"
    click FE_Pages "https://github.com/raunakgurud09/payments/blob/main/client/src/pages/Success.tsx"
    click FE_Pages "https://github.com/raunakgurud09/payments/blob/main/client/src/pages/Failure.tsx"
    click FE_Card "https://github.com/raunakgurud09/payments/blob/main/client/src/components/Card.tsx"
    click FE_Catalog "https://github.com/raunakgurud09/payments/blob/main/client/src/api/products.json"
    click FE_Const "https://github.com/raunakgurud09/payments/blob/main/client/src/constant.ts"

    click BE_Index "https://github.com/raunakgurud09/payments/blob/main/server/src/index.ts"
    click BE_App "https://github.com/raunakgurud09/payments/blob/main/server/src/app.ts"
    click R_Payment "https://github.com/raunakgurud09/payments/blob/main/server/src/routes/payment.routes.ts"
    click R_Health "https://github.com/raunakgurud09/payments/blob/main/server/src/routes/healthcheck.routes.ts"
    click C_Payment "https://github.com/raunakgurud09/payments/blob/main/server/src/controllers/payment/index.ts"
    click C_Payment "https://github.com/raunakgurud09/payments/tree/main/server/src/controllers/payment/"
    click C_Health "https://github.com/raunakgurud09/payments/blob/main/server/src/controllers/healthcheck.controllers.ts"
    click M_Order "https://github.com/raunakgurud09/payments/blob/main/server/src/model/order.ts"
    click P_DB "https://github.com/raunakgurud09/payments/blob/main/server/src/db/index.ts"
    click K_Const "https://github.com/raunakgurud09/payments/blob/main/server/src/constants/index.ts"
    click K_Const "https://github.com/raunakgurud09/payments/tree/main/server/src/constants/"
    click K_Env "https://github.com/raunakgurud09/payments/blob/main/server/.env.sample"

    %% =========================
    %% Styles (color-coded)
    %% =========================
    classDef person fill:#E9F2FF,stroke:#2563EB,stroke-width:1.5,color:#0B1B3A
    classDef frontend fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5,color:#0B1B3A
    classDef backend fill:#DCFCE7,stroke:#16A34A,stroke-width:1.5,color:#05230F
    classDef db fill:#E5E7EB,stroke:#374151,stroke-width:1.5,color:#111827
    classDef external fill:#FFEDD5,stroke:#C2410C,stroke-width:1.5,color:#3B1305
    classDef externalui fill:#FFE4C7,stroke:#9A3412,stroke-width:1.5,color:#3B1305
    classDef config fill:#F3E8FF,stroke:#7C3AED,stroke-width:1.5,color:#2A0A57
    classDef secrets fill:#FEE2E2,stroke:#DC2626,stroke-width:1.5,color:#3A0B0B
    classDef data fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5,color:#0A2230
    classDef model fill:#FFF7ED,stroke:#EA580C,stroke-width:1.5,color:#3B1305
    classDef step fill:#FFFFFF,stroke:#64748B,stroke-width:1.2,color:#0F172A,stroke-dasharray:3 3

    class User person
    class FE_App,FE_Pages,FE_Card frontend
    class FE_Catalog data
    class FE_Const config
    class BE_API,BE_Routes,BE_Controllers,BE_Index,BE_App,R_Payment,R_Health,C_Payment,C_Health backend
    class DB,P_DB db
    class RP_APIs,I_Razor external
    class RP_Checkout externalui
    class BE_Config,K_Const config
    class BE_Secrets,K_Env secrets
    class M_Order model
```
