# holdmyticket/holdmyticket-client-processor architecture

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

- Interactive diagram: https://gitdiagram.com/holdmyticket/holdmyticket-client-processor
- Repository: https://github.com/holdmyticket/holdmyticket-client-processor

## Overview

##### What this project is (type + purpose)
From the file tree + README, this is a **Node.js/JavaScript library published to npm** (not a deployed service). The core “product” is a reusable module named **`holdmyticket-client-processor`** that likely **normalizes/handles “client processing” flows** for HoldMyTicket (HMT), with explicit signs of **payment/processor integrations**:
- Tests mention: `processor-cards`, `processor-spreedly`, `processor-fullsteam`, plus `request`, `logging`, `utils`.
- Source contains `src/hmt-client-processor.js` (very likely the main entry point) and `src/fullsteamCodes/fullsteamCodes.js` (supporting constants/mappings).

- The **runtime module** (what consumers import and call)
- The **build pipeline** (Babel/Gulp producing `dist/` / `build/`)
- The **test harness** (Jest/Mocha-style tests in `src/__tests__`)

##### How to read the structure (what the directories imply)
Top-level:
- `src/` — authoritative source code.
- `src/hmt-client-processor.js` — likely the primary public API surface.
- `src/fullsteamCodes/fullsteamCodes.js` — likely a mapping table or translation layer for Fullsteam result/response codes.
- `src/__tests__/...` — unit/integration tests organized by concern (cards, spreedly, fullsteam, logging, request, utils).
- `src/test/test-data.js` — fixtures used in tests.
- `dist/` and/or `build/` — compiled artifacts (Babel output) that consumers actually receive when installed from npm.
- `Gulpfile.js` — build orchestration (dev vs publish modes).
- `babel.config.js` — JS transpilation rules.
- `package.json` — entry points, dependencies, scripts, versioning, publishing metadata.
- `.nvmrc` — expected Node version (important in build/publish lanes).

This suggests a **single-package repo** that outputs a distributable library, not multiple services.

##### What the README tells you to emphasize
- **Dev mode**: `gulp --type dev` (likely watch/build/test locally)
- **Publish mode**: `gulp --type publish` → bump `package.json` → `yarn publish` to npmjs.com

**Goal:** show how an application uses this npm package and which external systems it talks to.

**Main components to include**
##### Consumer Application (external)
- E.g., “HMT Web App”, “HMT Backend”, or “Merchant App” (whatever actually imports this library).
##### holdmyticket-client-processor (this library)
Break into internal components that are strongly implied by tests:
- **Core Processor API** (`src/hmt-client-processor.js`)
- **Request/HTTP layer** (implied by `hmt-client-processor-request.js` test)
- **Logging module** (implied by `...-logging.js` test)
- **Utilities module** (implied by `...-utils.js` test)
- **Cards flow module** (implied by `...-cards.js` test)
- **Spreedly adapter/integration** (implied by `...-spreedly.js` test)
- **Fullsteam adapter/integration** (implied by `...-fullsteam.js` test)
- **Fullsteam code mapping** (`src/fullsteamCodes/fullsteamCodes.js`)
##### External Services
- **Spreedly API** (tokenization/vault/payment gateway aggregator)
- **Fullsteam API** (payment processing / merchant services)

- Consumer App → `hmt-client-processor` (imports/calls public API)
- `hmt-client-processor` → Logging (internal dependency)
- `hmt-client-processor` → Utils (internal dependency)
- `hmt-client-processor` → Request/HTTP (internal dependency)
- Request/HTTP → Spreedly API (external call)
- Request/HTTP → Fullsteam API (external call)
- Fullsteam adapter → FullsteamCodes mapping (internal lookup)
- Cards flow → (Spreedly and/or Fullsteam adapters) depending on what “cards” means in your domain

**What to label explicitly**
- Protocols: “HTTPS/JSON” to external APIs
- Data objects: “payment request”, “token”, “authorization response”, “error mapping”

**Goal:** show how source becomes a published npm artifact, and where tests run.

**Main components to include**
##### Gulp build system (`Gulpfile.js`)
- Two modes: `dev` and `publish`
##### Test runner + suites
- Tests in `src/__tests__/`
- Fixtures in `src/test/test-data.js`
##### Package manager / publisher
- `yarn publish`
##### npm registry
- `npmjs.com` as the distribution endpoint
##### *(Optional but useful)* Node version constraint

- Dev → Gulp (dev mode) → Babel → outputs to `dist/`/`build/`
- Dev → Test runner → `src/__tests__` + `src/test/test-data.js`
- Publish path: Dev → Gulp (publish mode) → Babel build → artifacts → `yarn publish` → npm registry
- npm registry → Consumer App installs package

##### Important architectural patterns/design principles to call out
- **Adapter pattern for external processors**: “Spreedly adapter”, “Fullsteam adapter” isolate vendor-specific concerns.
- **Separation of concerns**: request/logging/utils are distinct modules used by the core processor.
- **Mapping/translation layer**: `fullsteamCodes` indicates normalization of external error/status codes into internal meanings.
- **Library distribution pattern**: source (`src`) → transpiled output (`dist`/`build`) → npm consumers.

Consumer App ↔ npm package ↔ external payment services.
Gulp dev/publish → Babel → dist/build → yarn publish → npm → consumers.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Diagram A — Runtime / Consumer View (Library Architecture)
%% =========================================================
subgraph "Diagram A — Runtime / Consumer View"
direction TB

A_Ext["Consumer Application\n(HMT App / Merchant App)"]:::external

subgraph "npm Package: holdmyticket-client-processor"
direction TB

A_pkg["Library Root\n(holdmyticket-client-processor)"]:::pkg

A_core["Core Processor API\n(exported module)"]:::lib

subgraph "Internal Modules"
direction TB
A_cards["Cards Flow Module"]:::lib
A_spreedly["Spreedly Adapter / Integration"]:::lib
A_fullsteam["Fullsteam Adapter / Integration"]:::lib
A_request["Request / HTTP Layer"]:::lib
A_logging["Logging Module"]:::lib
A_utils["Utilities Module"]:::lib

subgraph "Fullsteam Translation Layer"
direction TB
A_fs_dir["Fullsteam Codes Module (dir)"]:::lib
A_fs_codes["Fullsteam Codes Mapping\n(response/error normalization)"]:::lib
end
end

end

A_spreedly_api["Spreedly API"]:::external
A_fullsteam_api["Fullsteam API"]:::external

%% Runtime relationships
A_Ext -->|"imports/calls"| A_core

A_core -->|"orchestrates"| A_cards
A_core -->|"uses"| A_request
A_core -->|"uses"| A_logging
A_core -->|"uses"| A_utils

A_cards -->|"routes_to"| A_spreedly
A_cards -->|"routes_to"| A_fullsteam

A_spreedly -->|"calls_via"| A_request
A_fullsteam -->|"calls_via"| A_request

A_fullsteam -->|"maps_response_codes"| A_fs_codes
A_fs_dir -->|"contains"| A_fs_codes

A_request -->|"HTTPS/JSON"| A_spreedly_api
A_request -->|"HTTPS/JSON"| A_fullsteam_api

A_logging -.->|"captures_events/errors"| A_core
A_utils -.->|"helpers"| A_core
end

%% =========================================================
%% Diagram B — Build / Test / Publish Pipeline
%% =========================================================
subgraph "Diagram B — Build / Test / Publish Pipeline"
direction TB

B_dev["Developer Workstation"]:::external
B_node["Node Runtime\n(version pinned)"]:::tool
B_nvmrc["Node Version Constraint\n(.nvmrc)"]:::tool

B_pkgjson["Package Metadata\n(entrypoints/scripts/version)"]:::pkg

B_gulp["Gulp Build Orchestration\n(dev / publish modes)"]:::tool
B_babel["Babel Transpilation"]:::tool

B_src["Source Directory\n(src/)"]:::repo
B_core2["Core Processor API\n(src/hmt-client-processor.js)"]:::lib

B_tests_dir["Test Harness / Suites\n(src/__tests__/)"]:::test
B_t_cards["Cards Tests"]:::test
B_t_spreedly["Spreedly Tests"]:::test
B_t_fullsteam["Fullsteam Tests"]:::test
B_t_request["Request Tests"]:::test
B_t_logging["Logging Tests"]:::test
B_t_utils["Utils Tests"]:::test

B_testdata_dir["Test Data Directory\n(src/test/)"]:::test
B_testdata["Test Fixtures\n(src/test/test-data.js)"]:::test

B_dist["Compiled Artifacts\n(dist/)"]:::artifact
B_build["Compiled Artifacts\n(build/)"]:::artifact

B_yarn["yarn publish"]:::tool
B_npm["npm Registry\n(npmjs.com)"]:::external
B_consumer_install["Consumer installs package\n(yarn/npm install)"]:::external

%% Pipeline relationships
B_nvmrc -->|"pins_version"| B_node
B_node -->|"runs"| B_gulp
B_node -->|"runs"| B_yarn

B_dev -->|"edits"| B_src
B_src -->|"includes"| B_core2

B_dev -->|"runs_gulp --type dev"| B_gulp
B_gulp -->|"transpile"| B_babel
B_babel -->|"outputs"| B_dist
B_babel -->|"outputs"| B_build

B_dev -->|"runs_tests"| B_tests_dir
B_tests_dir -->|"uses_fixtures"| B_testdata
B_testdata_dir -->|"contains"| B_testdata

B_tests_dir -->|"executes"| B_t_cards
B_tests_dir -->|"executes"| B_t_spreedly
B_tests_dir -->|"executes"| B_t_fullsteam
B_tests_dir -->|"executes"| B_t_request
B_tests_dir -->|"executes"| B_t_logging
B_tests_dir -->|"executes"| B_t_utils

B_dev -->|"runs_gulp --type publish"| B_gulp
B_gulp -->|"reads/version_bump"| B_pkgjson
B_pkgjson -->|"drives_publish_metadata"| B_yarn
B_dist -->|"packaged"| B_yarn
B_build -->|"packaged"| B_yarn
B_yarn -->|"publishes"| B_npm

B_npm -->|"distributed_to"| B_consumer_install
end

%% =========================================================
%% Click Events (component mapping paths only; not shown in labels)
%% =========================================================
click A_pkg "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/package.json"
click B_pkgjson "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/package.json"

click A_core "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/hmt-client-processor.js"
click B_core2 "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/hmt-client-processor.js"

click A_fs_codes "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/fullsteamCodes/fullsteamCodes.js"
click A_fs_dir "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/src/fullsteamCodes/"

click B_tests_dir "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/src/__tests__/"
click B_t_cards "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-cards.js"
click B_t_spreedly "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-spreedly.js"
click B_t_fullsteam "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-fullsteam.js"
click B_t_request "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-request.js"
click B_t_logging "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-logging.js"
click B_t_utils "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/__tests__/hmt-client-processor-utils.js"

click B_testdata "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/src/test/test-data.js"
click B_testdata_dir "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/src/test/"
click B_src "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/src/"

click B_gulp "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/Gulpfile.js"
click B_babel "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/babel.config.js"

click B_dist "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/dist/"
click B_build "https://github.com/holdmyticket/holdmyticket-client-processor/tree/master/build/"
click B_nvmrc "https://github.com/holdmyticket/holdmyticket-client-processor/blob/master/.nvmrc"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
classDef pkg fill:#D1FAE5,stroke:#065F46,color:#064E3B,stroke-width:1px
classDef lib fill:#DBEAFE,stroke:#1D4ED8,color:#0B2A6F,stroke-width:1px
classDef tool fill:#FFEDD5,stroke:#C2410C,color:#7C2D12,stroke-width:1px
classDef repo fill:#F3F4F6,stroke:#374151,color:#111827,stroke-width:1px
classDef artifact fill:#FEF3C7,stroke:#B45309,color:#78350F,stroke-width:1px
classDef test fill:#FCE7F3,stroke:#9D174D,color:#831843,stroke-width:1px
```
