# razorpay/razorpay-java architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Java SDK (client library) for the Razorpay REST API (“razorpay-java”). It provides a strongly‐typed, high‐level Java interface over HTTP/JSON calls to the Razorpay payment platform.

##### File Structure Analysis
- Top‐level:
- pom.xml – Maven coordinates and dependencies
- README.md / documents/ – usage docs per resource
- src/main/java/com/razorpay:
- RazorpayClient.java – single entry point for SDK
- *Client.java classes – one per resource (PaymentClient, OrderClient, etc.)
- Domain model classes (Payment, Order, Customer, etc.)
- Core HTTP layer: ApiClient, ApiUtils, Constants, project.properties
- Validation/support: PayloadValidator, Utils, CustomTLSSocketFactory
- src/test: unit tests mocking HTTP to validate each client/resource.

##### README Insights
- SDK instantiation modes (key/secret or access_token)
- Supported resources listed under “Supported Resources” linking to documents/*.md
- Custom‐request escape hatch via razorpayClient.Payments.post(...)

a. Main Components
- User Application (any Java app using the SDK)
- RazorpayJavaSDK (with sub‐layers)
- Entry Point: RazorpayClient
- Resource Clients: AccountClient, PaymentClient, OrderClient, …
- HTTP Transport Layer: ApiClient (handles base URL, auth, headers), HttpURLConnection or Apache HTTP under the hood
- Domain Models: Payment, Order, Customer, etc.
- Utilities: PayloadValidator, ApiUtils, CustomTLSSocketFactory, ValidationConfig
- External System: Razorpay REST API endpoints

b. Relationships & Data Flow
1. User App invokes methods on RazorpayClient.
2. RazorpayClient dispatches to a ResourceClient (e.g., PaymentClient.create()).
3. ResourceClient builds a JSON payload (using domain models), calls ApiClient.
4. ApiClient serializes payload, adds authentication headers, issues HTTP request to Razorpay API.
5. API responds JSON – ApiClient deserializes into domain model.
6. Response model returns up through ResourceClient to User App.

c. Architectural Patterns & Principles
- Layered architecture:
- API‐Client Layer (HTTP concerns)
- Resource‐specific façade layer (*Client classes)
- Domain model layer (POJOs for JSON mapping)
- Separation of Concerns: validation (PayloadValidator), TLS config, utils isolated
- Extensibility: new resource clients follow the same pattern
- Testability: HTTP layer can be mocked in unit tests

d. Key Technologies/Frameworks
- Java 1.8+
- Maven for build & dependency management
- JSON serialization (org.json.* or cz.json)
- JUnit/TestNG (tests under src/test)

##### Elements
- Version (1.4.8) and authentication modes (Key/Secret vs Access Token).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        UA["Java Application"]:::user
    end

    %% SDK Layer
    subgraph "SDK (razorpay-java)"
        subgraph "Entry Point"
            RPC["RazorpayClient"]:::sdk
        end
        subgraph "Resource Clients"
            RC["PaymentClient, OrderClient, CustomerClient, AccountClient, ..."]:::sdk
        end
        subgraph "Domain Models"
            DM["Payment, Order, Customer, Invoice, Refund, ..."]:::sdk
        end
        subgraph "HTTP Transport Layer"
            AC["ApiClient"]:::sdk
            AU["ApiUtils"]:::sdk
            CN["Constants"]:::sdk
            PP["project.properties"]:::sdk
        end
        subgraph "Validation & Utilities"
            PV["PayloadValidator"]:::sdk
            UT["Utils"]:::sdk
            CT["CustomTLSSocketFactory"]:::sdk
            VC["ValidationConfig"]:::sdk
            VT["ValidationType"]:::sdk
        end
    end

    %% External API
    APIR["Razorpay REST API"]:::external

    %% Documentation
    subgraph "Documentation"
        DOCS["documents/*.md"]:::docs
    end

    %% Unit Tests
    subgraph "Unit Tests"
        UTs["src/test/java/com/razorpay/*Test.java"]:::test
    end

    %% Metadata
    PM["pom.xml"]:::meta
    RM["README.md"]:::meta
    LC["LICENSE.txt / CHANGELOG.md"]:::meta

    %% Data Flow
    UA -->|"new RazorpayClient(key,secret)"| RPC
    RPC -->|"createPayment(request)"| RC
    RC -->|"build JSON payload"| DM
    RC -->|"invoke()"| AC
    AC -->|"serialize + auth"| AU
    AU -->|"uses Constants"| CN
    AU -->|"loads properties"| PP
    AC -->|"HTTP POST /v1/payments"| APIR
    APIR -->|"200 OK + JSON"| AC
    AC -->|"deserialize response"| DM
    DM -->|"return domain model"| RC
    RC -->|"returns Payment"| RPC
    RPC -->|"returns Payment"| UA

    %% Click Events
    click RPC "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/RazorpayClient.java"
    click RC "https://github.com/razorpay/razorpay-java/tree/master/src/main/java/com/razorpay"
    click DM "https://github.com/razorpay/razorpay-java/tree/master/src/main/java/com/razorpay"
    click AC "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/ApiClient.java"
    click AU "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/ApiUtils.java"
    click CN "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/Constants.java"
    click PP "https://github.com/razorpay/razorpay-java/blob/master/src/main/resources/project.properties"
    click PV "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/PayloadValidator.java"
    click UT "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/Utils.java"
    click CT "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/CustomTLSSocketFactory.java"
    click VC "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/ValidationConfig.java"
    click VT "https://github.com/razorpay/razorpay-java/blob/master/src/main/java/com/razorpay/ValidationType.java"
    click DOCS "https://github.com/razorpay/razorpay-java/tree/master/documents"
    click UTs "https://github.com/razorpay/razorpay-java/tree/master/src/test/java/com/razorpay"
    click PM "https://github.com/razorpay/razorpay-java/blob/master/pom.xml"
    click RM "https://github.com/razorpay/razorpay-java/blob/master/README.md"
    click LC "https://github.com/razorpay/razorpay-java/blob/master/LICENSE.txt"

    %% Styles
    classDef user fill:#9f6,stroke:#333,stroke-width:1px;
    classDef sdk fill:#6cf,stroke:#333,stroke-width:1px;
    classDef external fill:#f96,stroke:#333,stroke-width:1px;
    classDef docs fill:#fc9,stroke:#333,stroke-width:1px;
    classDef test fill:#ccc,stroke:#333,stroke-width:1px;
    classDef meta fill:#eee,stroke:#333,stroke-width:1px;
```
