# tonderio/tonder-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/tonderio/tonder-sdk
- Repository: https://github.com/tonderio/tonder-sdk

## Overview

##### Project type and purpose
- This is a front‑end JavaScript/TypeScript SDK (tonder-web-sdk) designed to be embedded into merchant websites to provide payment checkout functionality (InlineCheckout and LiteCheckout).
- It exposes a widget that runs entirely in the browser, communicates with Tonder’s REST APIs, integrates with Skyflow (for card tokenization) and OpenPay (for APMs), and supports HMAC signature validation.

##### Top‑level structure highlights
- **src/** – Contains all SDK source code, organized by concern:
- **classes/**: Core classes (InlineCheckout, LiteInlineCheckout, 3DS handling, loaders)
- **data/**: Modules to call each external API (checkoutApi, cardApi, customerApi, apmApi, skyflowApi, openPayApi, businessApi)
- **helpers/**: Templating, style injection, validation utilities
- **shared/**: Constants, catalogs (logos, payment methods), shared utils (apiFetch)
- **index.js / index-dev.js / index.html**: Entry points for bundling and local dev/demo
- **types/** – TypeScript definitions for public interfaces and domain objects
- **webpack.config.js** – Bundles the SDK into a minified UMD/ESM library (v1/bundle.min.js)
- **samples/** – Example React app demonstrating SDK integration
- **cypress/** – End‑to‑end test suite with scenarios for widget mounting and payment flows

##### Key architectural patterns
- Modular layering:
a. **Presentation layer** (templating + style injection)
b. **SDK façade** (InlineCheckout and LiteCheckout classes, providing a simple public API)
c. **Business logic** (3DS flow, checkout configuration, event callbacks)
d. **Data access layer** (one module per external HTTP endpoint)
e. **Shared utilities** (HTTP fetch wrapper, HMAC helpers, validation, constants)
- Dependency inversion: public classes depend on abstracted API modules (e.g., customerApi, skyflowApi)
- Plugin‑style injection: the SDK dynamically injects HTML/CSS into the host page’s DOM

##### Main components
A. Host Web Application
- Optionally imports via NPM or `<script>` tag
- Instantiates `new InlineCheckout()` or `new LiteCheckout()`
- Provides merchant API key, returnUrl, styles, callbacks
B. Tonder Web SDK
1. **Public API** (InlineCheckout, LiteCheckout)
2. **UI Engine** (template-skeleton.js, template.js, styles.js)
3. **Business Controllers** (3dsHandler, BaseInlineCheckout, inlineCheckout.js, liteInlineCheckout.js)
4. **Data Access Modules** (checkoutApi.js, customerApi.js, cardApi.js, apmApi.js, skyflowApi.js, openPayApi.js, businessApi.js)
5. **Shared Utils/Constants** (apiFetch, validation functions, catalogs, constants)
6. **Type Definitions** (types/*.d.ts)
C. External Services
- **Tonder REST API** (the backend servicing payment creation, 3DS verification)
- **Skyflow Tokenization Service** (card field tokenization)
- **OpenPay APM Scripts** (handle certain payment methods)
- **HMAC Signing** (performed client‑side for the SDK or server‑side for direct REST calls)
D. Testing & Build Tools
- **Webpack** (build pipeline)
- **Cypress** (E2E tests mounting the widget and simulating payments)
- **ESLint / Prettier / Husky** (code quality and pre‑commit hooks)

##### Relationships & data flow
- Host App → instantiate SDK → **configureCheckout()** (loads initial payload)
- SDK → **injectCheckout()** → renders HTML into DOM
- User enters card/APM data → SDK Validation Helpers →
- for card: invokes Skyflow JS to tokenize sensitive data
- for APM: invokes OpenPay scripts if required
- SDK Data Access → calls Tonder REST via checkoutApi (attaching HMAC signature headers)
- For 3DS: SDK 3dsHandler intercepts redirect flow, returns result via `verify3dsTransaction()`
- Responses & errors bubble back to Host App via callbacks or returned Promises

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Application Layer
    subgraph "Host Web Application" 
        direction TB
        HostApp["Host App"]:::host
    end
    click HostApp "https://github.com/tonderio/tonder-sdk/tree/master/samples/react"

    %% SDK Public API Layer
    subgraph "SDK Public API" 
        direction TB
        InlineCheckout["InlineCheckout"]:::api
        LiteInlineCheckout["LiteInlineCheckout"]:::api
        BaseInlineCheckout["BaseInlineCheckout"]:::api
    end
    click InlineCheckout "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/inlineCheckout.js"
    click LiteInlineCheckout "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/LiteInlineCheckout.js"
    click BaseInlineCheckout "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/BaseInlineCheckout.js"

    %% UI Engine Layer
    subgraph "UI Engine (Templating & Styles)" 
        direction TB
        TemplateSkeleton["template-skeleton.js"]:::presentation
        Template["template.js"]:::presentation
        Styles["styles.js"]:::presentation
    end
    click TemplateSkeleton "https://github.com/tonderio/tonder-sdk/blob/master/src/helpers/template-skeleton.js"
    click Template "https://github.com/tonderio/tonder-sdk/blob/master/src/helpers/template.js"
    click Styles "https://github.com/tonderio/tonder-sdk/blob/master/src/helpers/styles.js"

    %% Business Logic Layer
    subgraph "Business Controllers" 
        direction TB
        ThreeDS["3dsHandler"]:::business
        CheckoutController["checkout.js"]:::business
        GlobalLoader["globalLoader"]:::business
    end
    click ThreeDS "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/3dsHandler.js"
    click CheckoutController "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/checkout.js"
    click GlobalLoader "https://github.com/tonderio/tonder-sdk/blob/master/src/classes/globalLoader.js"

    %% Data Access Layer
    subgraph "Data Access Modules" 
        direction TB
        CheckoutApi["checkoutApi.js"]:::data
        CardApi["cardApi.js"]:::data
        CustomerApi["customerApi.js"]:::data
        APMApi["apmApi.js"]:::data
        SkyflowApi["skyflowApi.js"]:::data
        OpenPayApi["openPayApi.js"]:::data
        BusinessApi["businessApi.js"]:::data
    end
    click CheckoutApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/checkoutApi.js"
    click CardApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/cardApi.js"
    click CustomerApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/customerApi.js"
    click APMApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/apmApi.js"
    click SkyflowApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/skyflowApi.js"
    click OpenPayApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/openPayApi.js"
    click BusinessApi "https://github.com/tonderio/tonder-sdk/blob/master/src/data/businessApi.js"

    %% Shared Utilities & Constants Layer
    subgraph "Shared Utilities & Constants" 
        direction TB
        ApiFetch["apiFetch.js"]:::shared
        ColorsConst["colors.js"]:::shared
        PaymentMethodsCatalog["paymentMethodsCatalog.js"]:::shared
    end
    click ApiFetch "https://github.com/tonderio/tonder-sdk/blob/master/src/shared/utils/apiFetch.js"
    click ColorsConst "https://github.com/tonderio/tonder-sdk/blob/master/src/shared/constants/colors.js"
    click PaymentMethodsCatalog "https://github.com/tonderio/tonder-sdk/blob/master/src/shared/catalog/paymentMethodsCatalog.js"

    %% External Services Layer
    subgraph "External Services" 
        direction TB
        TonderAPI["Tonder REST API"]:::external
        SkyflowService["Skyflow Tokenization"]:::external
        OpenPayService["OpenPay Scripts"]:::external
        HMAC["HMAC Signing"]:::external
    end

    %% Build & Test Tools Layer
    subgraph "Build & Test Infrastructure" 
        direction TB
        Webpack["webpack.config.js"]:::tool
        Cypress["cypress/"]:::tool
        ESLint["eslint.config.mjs"]:::tool
        Husky[".husky/pre-commit"]:::tool
    end
    click Webpack "https://github.com/tonderio/tonder-sdk/blob/master/webpack.config.js"
    click Cypress "https://github.com/tonderio/tonder-sdk/tree/master/cypress"
    click ESLint "https://github.com/tonderio/tonder-sdk/blob/master/eslint.config.mjs"
    click Husky "https://github.com/tonderio/tonder-sdk/tree/master/.husky/pre-commit"

    %% Data Flows
    HostApp -->|"instantiates SDK"| InlineCheckout
    InlineCheckout -->|"renders via"| TemplateSkeleton
    TemplateSkeleton --> Template
    Template --> Styles
    Styles -->|"injects into DOM"| HostApp

    InlineCheckout --> ThreeDS
    InlineCheckout --> CheckoutController
    CheckoutController --> GlobalLoader

    InlineCheckout --> CheckoutApi
    InlineCheckout --> CustomerApi
    InlineCheckout --> CardApi
    InlineCheckout --> APMApi
    InlineCheckout --> SkyflowApi
    InlineCheckout --> OpenPayApi

    CheckoutApi --> TonderAPI
    SkyflowApi --> SkyflowService
    OpenPayApi --> OpenPayService
    CheckoutApi --> HMAC

    %% Responses back to Host App
    TonderAPI -->|"response/promises"| HostApp
    SkyflowService --> HostApp
    OpenPayService --> HostApp

    %% Utilities usage
    InlineCheckout --> ApiFetch
    InlineCheckout --> ColorsConst
    InlineCheckout --> PaymentMethodsCatalog

    %% QA Infrastructure
    HostApp --> Cypress

    %% Legend Styles
    classDef host fill:#D3E5FF,stroke:#2B6CB0,color:#2B6CB0
    classDef presentation fill:#E0F2FE,stroke:#0284C7,color:#0284C7
    classDef business fill:#D1FAE5,stroke:#059669,color:#059669
    classDef data fill:#FFEDD5,stroke:#FB923C,color:#C2410C
    classDef shared fill:#F0FDF4,stroke:#22C55E,color:#166534
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#374151
    classDef tool fill:#FFF7ED,stroke:#F97316,color:#C2410C
    classDef api fill:#FEF3C7,stroke:#D97706,color:#92400E
```
