# etsms/hosted-payments architecture

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

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

## Overview

##### Project type and purpose
- This is a JavaScript/CSS library (“Hosted Payments”) that provides hosted payment UIs (checkout, e-shop, gift card, loyalty, general payments) to be embedded in merchant websites.
- The README shows it’s intended for browser integration via jQuery v3+, loaded from a CDN, then communicates with Elavon’s payment servers.

##### File structure
- Top‐level configuration:
- package.json, package-lock.json (npm)
- bower.json (Bower)
- gulpfile.js (build tasks)
- config.rb (Compass/SASS)
- Jenkinsfile (CI)
- Source directory:
- src/*.sass (one .sass per plugin flavor)
- Distribution directory:
- dist/*.js, *.css (minified plugins)
- dist/hosted-*.html (demo pages)
- dist/images
- Demo entry point: demo.html
- No backend code—pure client & build assets.

##### Extract architecture insights from README
- Library is consumed via <script> & <link> tags from jsDelivr CDN.
- Relies on jQuery as a peer dependency.
- On initialization, it renders iframes or fields that POST data directly to the hosted payment gateway.
- Callbacks return JSON success/error objects to the embedding page.

##### Main components
a. Developer environment (local machine, CI/CD):
- Source code (src/*.sass)
- Build pipeline (gulp, Node.js/npm, Bower, Compass)
- CI server (Jenkins)
- Output artifacts pushed to GitHub and CDN.
b. CDN & Artifact Storage:
- jsDelivr (serving hosted-payments.min.js & .css)
- GitHub Releases (versioned dist directory)
c. Client Browser (merchant site):
- Merchant’s HTML page
- jQuery library
- Hosted Payments JS/CSS assets
- Rendered iframes or input fields
d. External Payment Gateway:
- Elavon Hosted Payments endpoint (HTTPS)
- Processes card/bank data
- Returns callback JSON to the client
e. Developer Application Code:
- Initializes the library
- Listens for callback events (success, error)
- Handles UI updates, business logic, order fulfillment

##### Relationships & interactions
- Build pipeline compiles SASS → CSS and bundles JS → creates dist.
- CI (Jenkins) runs tests/builds and publishes dist to GitHub and triggers CDN sync.
- Merchant page loads jQuery → then loads hosted-payments.min.js/css from CDN.
- Hosted Payments code injects UI and iframes that POST to Elavon’s servers.
- Elavon gateway processes transaction and responds with JSON callback to browser.
- Hosted-payments.js captures callback and dispatches events to merchant’s code.

##### Architectural patterns & principles
- Plugin/module pattern: each payment flavor is a separate JS module.
- Build automation: single gulpfile orchestrates SASS compile, JS minification.
- CDN delivery: static assets are decoupled from merchant servers.
- Security by isolation: sensitive entry fields are hosted in iframes on secure gateway.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        DS["SASS Plugins (src/jquery.hosted-*.sass)"]:::static
        GL["Build Config (gulpfile.js)"]:::static
        NP["Node Config (package.json & package-lock.json)"]:::static
        BW["Bower Config (bower.json)"]:::static
        CR["Compass/SASS Config (config.rb)"]:::static
        RD["Project Docs (README.md)"]:::static
        LI["License (LICENSE)"]:::static
        GI["Git Ignore (.gitignore)"]:::static
        DM["Local Demo (demo.html)"]:::static
    end

    subgraph "CI/CD"
        JC["Jenkins CI (Jenkinsfile)"]:::static
    end

    subgraph "Build Pipeline"
        BP["Build Pipeline (gulp + npm + Compass)"]:::static
    end

    subgraph "Artifacts"
        DJ["JS & CSS Libraries (dist/jquery.hosted-*.js & .css)"]:::static
        DH["Demo Pages (dist/hosted-*.html)"]:::static
        DI["Images (dist/images/)"]:::static
    end

    GH[(GitHub Releases)]:::static
    CD["jsDelivr CDN"]:::external

    subgraph "Merchant Browser"
        JQ["jQuery"]:::runtime
        HP["Hosted Payments Library"]:::runtime
        MC["Merchant App Code"]:::runtime
    end

    EG["Elavon Payment Gateway"]:::external

    %% Relationships
    DS --> BP
    GL --> BP
    NP --> BP
    BW --> BP
    CR --> BP
    JC --> BP
    BP --> DJ
    BP --> DH
    BP --> DI
    DJ --> GH
    DH --> GH
    DI --> GH
    GH --> CD
    CD --> JQ
    CD --> HP
    JQ --> HP
    HP -->|"inject UI & iframe"| EG
    EG -->|"JSON callback"| HP
    HP -->|"events"| MC
    DM --> JQ
    DM --> HP
    DM --> MC

    %% Click Events
    click DS "https://github.com/etsms/hosted-payments/blob/master/src/jquery.hosted-*.sass"
    click GL "https://github.com/etsms/hosted-payments/blob/master/gulpfile.js"
    click NP "https://github.com/etsms/hosted-payments/blob/master/package.json"
    click BW "https://github.com/etsms/hosted-payments/blob/master/bower.json"
    click CR "https://github.com/etsms/hosted-payments/blob/master/config.rb"
    click RD "https://github.com/etsms/hosted-payments/blob/master/README.md"
    click LI "https://github.com/etsms/hosted-payments/tree/master/LICENSE"
    click GI "https://github.com/etsms/hosted-payments/blob/master/.gitignore"
    click DM "https://github.com/etsms/hosted-payments/blob/master/demo.html"
    click JC "https://github.com/etsms/hosted-payments/tree/master/Jenkinsfile"
    click DJ "https://github.com/etsms/hosted-payments/blob/master/dist/jquery.hosted-*.js"
    click DH "https://github.com/etsms/hosted-payments/blob/master/dist/hosted-*.html"
    click DI "https://github.com/etsms/hosted-payments/tree/master/dist/images/"

    %% Styles
    classDef static fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef runtime fill:#e6ffe6,stroke:#333,stroke-width:1px
    classDef external fill:#ffe6cc,stroke:#333,stroke-width:1px
```
