# xendit/xendit-node architecture

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

- Interactive diagram: https://gitdiagram.com/xendit/xendit-node
- Repository: https://github.com/xendit/xendit-node

## Overview

##### Project Type and Purpose
- This is an open-source Node.js SDK that wraps Xendit’s REST API endpoints, providing TypeScript-typed clients for products such as Invoice, PaymentRequest, PaymentMethod, Refund, Transaction, Balance, Customer and Payout.
- Its goal is to offer application developers a convenient, modular interface to invoke Xendit services from server-side code.

##### File Structure Analysis
- Top-Level Modules:
– balance_and_transaction, customer, invoice, payment_method, payment_request, payout, refund
– Each module contains an apis/ directory (methods to call endpoints) and a models/ directory (TypeScript interfaces representing request/response payloads).
- Core Runtime:
– runtime.ts defines the HTTP client abstraction (configuration of API key, custom URL, request/response middleware).
- Configuration & Tooling:
– openapi-generator files signal that module code is generated from an OpenAPI spec.
– .eslintrc.json, tsconfig.json, package.json drive linting, compilation and package metadata.
- Documentation & Testing:
– docs/ holds Markdown files for each model and API overview.
– test/ contains unit tests (invoice.test.ts, payment_api.test.ts) and test utilities.

##### README Insights
- Confirms project purpose: a Node SDK instantiated with a secretKey (and optional URL override).
- Lists supported products and points to documentation per product.
- Highlights TypeScript support and Node 18+ requirement.

a. Main Components
– Client Application: user-written Node.js code using the SDK
– XenditNodeSDK Core:
- Configuration Layer (secretKey, xenditURL, timeout)
- Runtime HTTP Client (runtime.ts)
- Product Modules (apis + models for each product)
– External Services: Xendit REST API endpoints on https://api.xendit.co
– Developer Tools: openapi-generator, TypeScript compiler, Jest test runner
b. Relationships and Data Flow
1. Client Application calls a product method (e.g., xenditClient.Invoice.createInvoice).
2. Product Module’s API class constructs the HTTP request object and passes it to Runtime HTTP Client.
3. Runtime sends the request over HTTPS to the Xendit API.
4. Xendit API returns JSON response; Runtime deserializes it into the corresponding model interface.
5. Response model is returned to the Client Application.
6. Tests simulate scenarios by invoking methods against either a mock server or the real API (via custom xenditURL).
c. Architectural Patterns and Principles
– Modularization: one module per Xendit product to enforce separation of concerns.
– Code Generation: consistent models and API clients are generated from a shared OpenAPI definition, ensuring parity with the server’s contract.
– Dependency Injection: clients accept configuration parameters to allow testing against alternative endpoints.
– Layered Architecture:
- Presentation (public API surface exposed by index.ts)
- Business Logic (API classes in apis/)
- Data Models (interfaces in models/)
- Infrastructure (runtime.ts HTTP layer)
d. Key Technologies and Libraries
– Node.js (runtime environment)
– TypeScript (static typing, code generation)
– Axios or Fetch (HTTP calls abstracted in runtime.ts)
– OpenAPI Generator (automated client and model code generation)
– Jest (testing framework)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client Application
    ClientApp["Client Application"]:::external

    %% SDK Core
    subgraph "XenditNodeSDK" 
        direction TB

        subgraph "Configuration Layer"
            direction TB
            Index["index.ts (Public API)"]:::internal
            click Index "https://github.com/xendit/xendit-node/blob/master/index.ts"
            Package["package.json"]:::internal
            click Package "https://github.com/xendit/xendit-node/blob/master/package.json"
            TSConfig["tsconfig.json"]:::internal
            click TSConfig "https://github.com/xendit/xendit-node/blob/master/tsconfig.json"
            ESLint[".eslintrc.json"]:::internal
            click ESLint "https://github.com/xendit/xendit-node/blob/master/.eslintrc.json"
        end

        subgraph "Runtime HTTP Layer"
            direction TB
            Runtime["runtime.ts"]:::internal
            click Runtime "https://github.com/xendit/xendit-node/blob/master/runtime.ts"
        end

        subgraph "Product Modules"
            direction TB

            subgraph "Balance & Transaction"
                direction TB
                BTIndex["balance_and_transaction/index.ts"]:::internal
                click BTIndex "https://github.com/xendit/xendit-node/blob/master/balance_and_transaction/index.ts"
                BalanceAPI["Balance.ts"]:::internal
                click BalanceAPI "https://github.com/xendit/xendit-node/blob/master/balance_and_transaction/apis/Balance.ts"
                TransactionAPI["Transaction.ts"]:::internal
                click TransactionAPI "https://github.com/xendit/xendit-node/blob/master/balance_and_transaction/apis/Transaction.ts"
                BTModels["models/*.ts"]:::internal
                click BTModels "https://github.com/xendit/xendit-node/tree/master/balance_and_transaction/models"
            end

            subgraph "Customer"
                direction TB
                CustIndex["customer/index.ts"]:::internal
                click CustIndex "https://github.com/xendit/xendit-node/blob/master/customer/index.ts"
                CustomerAPI["Customer.ts"]:::internal
                click CustomerAPI "https://github.com/xendit/xendit-node/blob/master/customer/apis/Customer.ts"
                CustModels["models/*.ts"]:::internal
                click CustModels "https://github.com/xendit/xendit-node/tree/master/customer/models"
            end

            subgraph "Invoice"
                direction TB
                InvIndex["invoice/index.ts"]:::internal
                click InvIndex "https://github.com/xendit/xendit-node/blob/master/invoice/index.ts"
                InvoiceAPI["Invoice.ts"]:::internal
                click InvoiceAPI "https://github.com/xendit/xendit-node/blob/master/invoice/apis/Invoice.ts"
                InvModels["models/*.ts"]:::internal
                click InvModels "https://github.com/xendit/xendit-node/tree/master/invoice/models"
            end

            subgraph "PaymentMethod"
                direction TB
                PMIndex["payment_method/index.ts"]:::internal
                click PMIndex "https://github.com/xendit/xendit-node/blob/master/payment_method/index.ts"
                PMAPI["PaymentMethod.ts"]:::internal
                click PMAPI "https://github.com/xendit/xendit-node/blob/master/payment_method/apis/PaymentMethod.ts"
                PMModels["models/*.ts"]:::internal
                click PMModels "https://github.com/xendit/xendit-node/tree/master/payment_method/models"
            end

            subgraph "PaymentRequest"
                direction TB
                PRIndex["payment_request/index.ts"]:::internal
                click PRIndex "https://github.com/xendit/xendit-node/blob/master/payment_request/index.ts"
                PRAPI["PaymentRequest.ts"]:::internal
                click PRAPI "https://github.com/xendit/xendit-node/blob/master/payment_request/apis/PaymentRequest.ts"
                PRModels["models/*.ts"]:::internal
                click PRModels "https://github.com/xendit/xendit-node/tree/master/payment_request/models"
            end

            subgraph "Payout"
                direction TB
                PayoutIndex["payout/index.ts"]:::internal
                click PayoutIndex "https://github.com/xendit/xendit-node/blob/master/payout/index.ts"
                PayoutAPI["Payout.ts"]:::internal
                click PayoutAPI "https://github.com/xendit/xendit-node/blob/master/payout/apis/Payout.ts"
                PayoutModels["models/*.ts"]:::internal
                click PayoutModels "https://github.com/xendit/xendit-node/tree/master/payout/models"
            end

            subgraph "Refund"
                direction TB
                RefundIndex["refund/index.ts"]:::internal
                click RefundIndex "https://github.com/xendit/xendit-node/blob/master/refund/index.ts"
                RefundAPI["Refund.ts"]:::internal
                click RefundAPI "https://github.com/xendit/xendit-node/blob/master/refund/apis/Refund.ts"
                RefundModels["models/*.ts"]:::internal
                click RefundModels "https://github.com/xendit/xendit-node/tree/master/refund/models"
            end

        end
    end

    %% External Xendit API
    XenditAPI["External Xendit REST API"]:::external

    %% Developer Tools
    subgraph "Developer Tools"
        direction TB
        OpenAPIGen[".openapi-generator/"]:::tools
        click OpenAPIGen "https://github.com/xendit/xendit-node/tree/master/.openapi-generator/VERSION"
        TSCompiler["TypeScript Compiler"]:::tools
        ESLintTool["ESLint"]:::tools
        Jest["Jest Test Runner"]:::tools
        GitHubCI["generate-release-tag.yml"]:::tools
        click GitHubCI "https://github.com/xendit/xendit-node/blob/master/.github/workflows/generate-release-tag.yml"
    end

    %% Documentation & Testing
    subgraph "Documentation"
        direction TB
        Docs["docs/"]:::docs
        click Docs "https://github.com/xendit/xendit-node/tree/master/docs/"
    end

    subgraph "Testing (Jest)"
        direction TB
        TestInv["invoice.test.ts"]:::test
        click TestInv "https://github.com/xendit/xendit-node/blob/master/test/invoice.test.ts"
        TestPay["payment_api.test.ts"]:::test
        click TestPay "https://github.com/xendit/xendit-node/blob/master/test/payment_api.test.ts"
        TestUtil["test_util.ts"]:::test
        click TestUtil "https://github.com/xendit/xendit-node/blob/master/test/utils/test_util.ts"
        EnvTest[".env.test"]:::test
        click EnvTest "https://github.com/xendit/xendit-node/blob/master/test/.env.test"
    end

    %% Data Flow
    ClientApp -->|"calls createInvoice()"| Index
    Index -->|"injects secretKey"| Runtime
    Index -->|"exposes modules"| BalanceAPI
    Index -->|"exposes modules"| CustomerAPI
    Index -->|"exposes modules"| InvoiceAPI
    Index -->|"exposes modules"| PMAPI
    Index -->|"exposes modules"| PRAPI
    Index -->|"exposes modules"| PayoutAPI
    Index -->|"exposes modules"| RefundAPI

    BalanceAPI -->|"build request"| Runtime
    CustomerAPI -->|"build request"| Runtime
    InvoiceAPI -->|"build request"| Runtime
    PMAPI -->|"build request"| Runtime
    PRAPI -->|"build request"| Runtime
    PayoutAPI -->|"build request"| Runtime
    RefundAPI -->|"build request"| Runtime

    Runtime -->|"HTTPS Request"| XenditAPI
    XenditAPI -->|"JSON Response"| Runtime

    Runtime -->|"deserialize to models"| BTModels
    Runtime -->|"deserialize to models"| CustModels
    Runtime -->|"deserialize to models"| InvModels
    Runtime -->|"deserialize to models"| PMModels
    Runtime -->|"deserialize to models"| PRModels
    Runtime -->|"deserialize to models"| PayoutModels
    Runtime -->|"deserialize to models"| RefundModels

    BTModels -->|"return data"| ClientApp
    CustModels -->|"return data"| ClientApp
    InvModels -->|"return data"| ClientApp
    PMModels -->|"return data"| ClientApp
    PRModels -->|"return data"| ClientApp
    PayoutModels -->|"return data"| ClientApp
    RefundModels -->|"return data"| ClientApp

    %% Developer Tools Integration
    OpenAPIGen -->|"generate apis & models"| BalanceAPI
    OpenAPIGen -->|"generate apis & models"| CustomerAPI
    OpenAPIGen -->|"generate apis & models"| InvoiceAPI
    OpenAPIGen -->|"generate apis & models"| PMAPI
    OpenAPIGen -->|"generate apis & models"| PRAPI
    OpenAPIGen -->|"generate apis & models"| PayoutAPI
    OpenAPIGen -->|"generate apis & models"| RefundAPI

    TSCompiler -->|"compile .ts to .js"| Index
    ESLintTool -->|"lint code"| Index
    Jest -->|"run tests"| TestInv
    Jest -->|"run tests"| TestPay

    GitHubCI -->|"trigger release"| Package

    Docs -->|"reference for developers"| ClientApp

    %% Styles
    classDef internal fill:#e0f7fa,stroke:#00838f
    classDef external fill:#ffe0b2,stroke:#ff6f00
    classDef tools fill:#e8f5e9,stroke:#2e7d32
    classDef docs fill:#f3e5f5,stroke:#6a1b9a
    classDef test fill:#fff3e0,stroke:#ef6c00
```
