# paypal/paypal-sdk-client architecture

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

- Interactive diagram: https://gitdiagram.com/paypal/paypal-sdk-client
- Repository: https://github.com/paypal/paypal-sdk-client

## Overview

1. **What this repo is**
   - `@paypal/sdk-client` is a shared utility library for PayPal/Braintree SDK modules.
   - It has two distinct runtime surfaces: a **browser/client-side API** for reading SDK context and running client utilities, and a **server-side binding** for validating and rehydrating SDK metadata into a script tag.

2. **Top-level package shape**
   - The main implementation lives in `src/`.
   - A separate `server/` directory contains the server-specific entrypoint and render helpers.
   - The root `index.js` likely acts as the package entry/export surface, while `__sdk__.js` suggests this package also supports SDK bundling conventions used in the PayPal codebase.

3. **Core architectural boundary: client vs server**
   - The codebase is split around where the logic runs:
     - **Client-side**: reads global/session state, computes URLs, manages experiments, tracking, and API-related helpers.
     - **Server-side**: accepts serialized SDK metadata from the client, validates it, and produces a safe script loader tag to inject into HTML.
   - This boundary matters because the server must preserve exact SDK URL matching while preventing tampering/XSS.

4. **Metadata flow is the central data path**
   - The main flow described in the README is:
     1. The parent/client generates SDK metadata with `getSdkMeta()`.
     2. That metadata is passed to a child window/frame (often via zoid `queryParam` props).
     3. The server receives `sdkMeta` and calls `unpackSDKMeta(...)`.
     4. The server uses the unpacked result to render a script tag via `getSDKLoader(...)`.
   - This is the key architectural diagram line: **client generates serialized context → server validates and turns it into a loader tag → child frame loads the exact SDK URL**.

5. **Security and validation boundary**
   - `server/` is not just a serializer; it is a trust boundary.
   - `unpackSDKMeta` is expected to reject tampered payloads, and the README explicitly says validation failures should become server errors.
   - This protects script injection and ensures the SDK URL used in the child matches the parent exactly.

6. **Client utilities subsystem**
   - `src/` contains several helper areas that appear to support SDK behavior:
     - `config`, `constants`, `domains`, `global`, `session`, `paypalSession`
     - `script`, `meta`, `api`, `graphql`
     - `tracking`, `events`, `logger`, `fraudnet`
     - `dpop`, `experiment`, `interface`, `errors`, `utils`
   - These are likely composed into the public API exposed from `src/index.js`.
   - Architecturally, this looks like a **utility-and-context layer** rather than a UI layer.

7. **Environment and runtime context helpers**
   - Several modules indicate this library centralizes browser/global environment detection and per-session state:
     - `global.js` and `session.js` suggest cross-window/global access patterns.
     - `domains.js` and `config.js` suggest environment selection and URL derivation.
     - `meta.js` and `paypalSession.js` likely translate SDK runtime context into structured metadata consumed by other modules.
   - These helpers matter because the SDK must work consistently across parent pages, iframes, popups, and server rendering.

8. **Integration with external PayPal/Braintree services**
   - The repo includes modules named `api`, `graphql`, `fraudnet`, and `tracking`, which implies it supports outbound integration with multiple PayPal backend services.
   - `dpop.js` suggests support for proof-of-possession or request-binding style security in some flows.
   - These integrations are likely abstracted so SDK components can share request construction, identifiers, and logging conventions.

9. **Server package structure**
   - `server/index.js`, `server/meta.jsx`, and `server/util.js` indicate the server side provides a small render/loader subsystem rather than a full app server.
   - The JSX file suggests the server loader tag is rendered via a component-like abstraction.
   - Tests in `server/meta.test.js` and `server/meta.integration.test.js` suggest the server boundary is heavily validated for both logic and end-to-end behavior.

10. **Testing strategy**
   - The repo uses **Vitest** for unit/integration tests (`*.test.js` across `src/` and `server/`).
   - `vitestSetup.js`, `test/globals.js`, and `test/helpers.js` indicate shared test harnesses for browser-like globals and fixtures.
   - This is important architecturally because much of the library depends on runtime environment simulation, not just pure functions.

11. **Build and transpilation pipeline**
   - Tooling includes Babel, Vite, and Webpack configs, which suggests the package supports multiple build targets or compatibility modes.
   - Flow typing is present via `.flowconfig` and `flow-typed/`, so the codebase is designed around static typing for runtime-shared utilities.
   - This matters because the library must ship consumable code for both Node/server and browser contexts.

12. **Publishing and CI/CD**
   - GitHub Actions workflows (`main.yml`, `publish.yml`) and `publish.sh` indicate automated validation and npm release publishing.
   - Code coverage, linting, pre-commit hooks, and formatting are part of the repository’s quality gates, but they do not change runtime architecture.

13. **Likely public API surface**
   - The README highlights `getClientID`, `getSdkMeta`, and `unpackSDKMeta` as the main external-facing functions.
   - These functions represent the two user-facing responsibilities of the package:
     - extract shared SDK/client context in the browser,
     - validate and reconstruct SDK metadata on the server.

14. **Diagram-friendly summary**
   - If you are drawing the architecture, model it as:
     - **Parent SDK/client runtime** producing metadata and environment-specific helpers,
     - **Serialized `sdkMeta` transport** between parent and child,
     - **Server validation/render layer** generating the exact matching script tag,
     - **Shared utility modules** supporting API calls, domains, sessions, tracking, experiments, and security-sensitive URL/script construction.

Main entry points: [`src/index.js`](https://github.com/paypal/paypal-sdk-client/blob/main/src/index.js) (Client API), [`src/meta.js`](https://github.com/paypal/paypal-sdk-client/blob/main/src/meta.js) (SDK meta), [`server/index.js`](https://github.com/paypal/paypal-sdk-client/blob/main/server/index.js) (Server API), [`src/script.js`](https://github.com/paypal/paypal-sdk-client/blob/main/src/script.js) (Script loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client runtime"]
  node_client_index["Client API<br/>public api<br/>[index.js]"]
  node_client_meta["SDK meta<br/>context model<br/>[meta.js]"]
  node_client_global(("Global state<br/>runtime env<br/>[global.js]"))
  node_client_session[("Session state<br/>session store<br/>[session.js]")]
  node_client_config["Config<br/>[config.js]"]
  node_client_domains{{"Domains<br/>url routing<br/>[domains.js]"}}
  node_client_script["Script loader<br/>loader utils<br/>[script.js]"]
  node_client_api["API client<br/>service client<br/>[api.js]"]
  node_client_graphql["GraphQL<br/>service client<br/>[graphql.js]"]
  node_client_tracking["Tracking<br/>telemetry<br/>[tracking.js]"]
  node_client_fraudnet["FraudNet<br/>fraud integration<br/>[fraudnet.js]"]
  node_client_dpop["DPoP<br/>security helper<br/>[dpop.js]"]
  node_client_sessionmeta["PayPal session<br/>session metadata<br/>[paypalSession.js]"]
end

subgraph group_server["Server runtime"]
  node_server_entry["Server API<br/>server entry<br/>[index.js]"]
  node_server_unpack["Unpack meta<br/>validator<br/>[meta.jsx]"]
  node_server_loader["Loader tag<br/>renderer<br/>[meta.jsx]"]
  node_server_util["Server utils<br/>server helpers<br/>[util.js]"]
end

subgraph group_tooling["Tooling"]
  node_tool_test["Tests<br/>test harness<br/>[vitestSetup.js]"]
  node_tool_build["Build config<br/>build system<br/>[vite.config.js]"]
  node_tool_ci["Release CI<br/>automation<br/>[main.yml]"]
end

node_root["Package entry<br/>exports<br/>[index.js]"]
node_sdkbundle["SDK shim<br/>bundle hook<br/>[__sdk__.js]"]

node_root -->|"exports"| node_client_index
node_root -->|"exports"| node_server_entry
node_root -.->|"bundle hook"| node_sdkbundle
node_client_index -->|"creates"| node_client_meta
node_client_index -->|"uses"| node_client_script
node_client_index -->|"uses"| node_client_api
node_client_index -->|"uses"| node_client_tracking
node_client_index -->|"uses"| node_client_fraudnet
node_client_index -->|"uses"| node_client_dpop
node_client_meta -->|"reads"| node_client_global
node_client_meta -->|"reads"| node_client_session
node_client_meta -->|"uses"| node_client_config
node_client_meta -->|"uses"| node_client_domains
node_client_meta -->|"emits"| node_client_sessionmeta
node_client_script -->|"resolves"| node_client_config
node_client_script -->|"resolves"| node_client_domains
node_client_api -->|"specializes"| node_client_graphql
node_server_entry -->|"validates"| node_server_unpack
node_server_entry -->|"renders"| node_server_loader
node_server_unpack -->|"uses"| node_server_util
node_server_loader -->|"uses"| node_server_util
node_client_meta -->|"sdkMeta"| node_server_unpack
node_server_loader -->|"loads"| node_client_script
node_tool_test -.->|"covers"| node_client_index
node_tool_test -.->|"covers"| node_server_entry
node_tool_build -.->|"builds"| node_client_index
node_tool_build -.->|"builds"| node_server_entry
node_tool_ci -.->|"runs"| node_tool_test
node_tool_ci -.->|"publishes"| node_tool_build

click node_root "https://github.com/paypal/paypal-sdk-client/blob/main/index.js"
click node_sdkbundle "https://github.com/paypal/paypal-sdk-client/blob/main/__sdk__.js"
click node_client_index "https://github.com/paypal/paypal-sdk-client/blob/main/src/index.js"
click node_client_meta "https://github.com/paypal/paypal-sdk-client/blob/main/src/meta.js"
click node_client_global "https://github.com/paypal/paypal-sdk-client/blob/main/src/global.js"
click node_client_session "https://github.com/paypal/paypal-sdk-client/blob/main/src/session.js"
click node_client_config "https://github.com/paypal/paypal-sdk-client/blob/main/src/config.js"
click node_client_domains "https://github.com/paypal/paypal-sdk-client/blob/main/src/domains.js"
click node_client_script "https://github.com/paypal/paypal-sdk-client/blob/main/src/script.js"
click node_client_api "https://github.com/paypal/paypal-sdk-client/blob/main/src/api.js"
click node_client_graphql "https://github.com/paypal/paypal-sdk-client/blob/main/src/graphql.js"
click node_client_tracking "https://github.com/paypal/paypal-sdk-client/blob/main/src/tracking.js"
click node_client_fraudnet "https://github.com/paypal/paypal-sdk-client/blob/main/src/fraudnet.js"
click node_client_dpop "https://github.com/paypal/paypal-sdk-client/blob/main/src/dpop.js"
click node_client_sessionmeta "https://github.com/paypal/paypal-sdk-client/blob/main/src/paypalSession.js"
click node_server_entry "https://github.com/paypal/paypal-sdk-client/blob/main/server/index.js"
click node_server_unpack "https://github.com/paypal/paypal-sdk-client/blob/main/server/meta.jsx"
click node_server_loader "https://github.com/paypal/paypal-sdk-client/blob/main/server/meta.jsx"
click node_server_util "https://github.com/paypal/paypal-sdk-client/blob/main/server/util.js"
click node_tool_test "https://github.com/paypal/paypal-sdk-client/blob/main/vitestSetup.js"
click node_tool_build "https://github.com/paypal/paypal-sdk-client/blob/main/vite.config.js"
click node_tool_ci "https://github.com/paypal/paypal-sdk-client/blob/main/.github/workflows/main.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_index,node_client_meta,node_client_global,node_client_session,node_client_config,node_client_domains,node_client_script,node_client_api,node_client_graphql,node_client_tracking,node_client_fraudnet,node_client_dpop,node_client_sessionmeta toneBlue
class node_server_entry,node_server_unpack,node_server_loader,node_server_util toneAmber
class node_tool_test,node_tool_build,node_tool_ci toneMint
class node_root,node_sdkbundle toneNeutral
```

## Components

### Client runtime

Browser-side SDK context, metadata, and shared utility modules.

- [Client API](https://github.com/paypal/paypal-sdk-client/blob/main/src/index.js): public api · Main browser-side exports assembled from shared modules. · `src/index.js`
- [SDK meta](https://github.com/paypal/paypal-sdk-client/blob/main/src/meta.js): context model · Builds serialized SDK metadata from client/runtime state. · `src/meta.js`
- [Global state](https://github.com/paypal/paypal-sdk-client/blob/main/src/global.js): runtime env · Accesses browser/global runtime context across frames and windows. · `src/global.js`
- [Session state](https://github.com/paypal/paypal-sdk-client/blob/main/src/session.js): session store · Manages per-session SDK state and identifiers. · `src/session.js`
- [Config](https://github.com/paypal/paypal-sdk-client/blob/main/src/config.js): environment config · Resolves environment-specific settings and SDK configuration. · `src/config.js`
- [Domains](https://github.com/paypal/paypal-sdk-client/blob/main/src/domains.js): url routing · Derives domain and endpoint selection for SDK requests. · `src/domains.js`
- [Script loader](https://github.com/paypal/paypal-sdk-client/blob/main/src/script.js): loader utils · Constructs and manages SDK script URLs and loading behavior. · `src/script.js`
- [API client](https://github.com/paypal/paypal-sdk-client/blob/main/src/api.js): service client · Builds outbound API requests for SDK services. · `src/api.js`
- [GraphQL](https://github.com/paypal/paypal-sdk-client/blob/main/src/graphql.js): service client · Specialized GraphQL integration for backend queries. · `src/graphql.js`
- [Tracking](https://github.com/paypal/paypal-sdk-client/blob/main/src/tracking.js): telemetry · Coordinates tracking and analytics events. · `src/tracking.js`
- [FraudNet](https://github.com/paypal/paypal-sdk-client/blob/main/src/fraudnet.js): fraud integration · Fraud and risk integration helpers. · `src/fraudnet.js`
- [DPoP](https://github.com/paypal/paypal-sdk-client/blob/main/src/dpop.js): security helper · Proof-of-possession or request-binding support. · `src/dpop.js`
- [PayPal session](https://github.com/paypal/paypal-sdk-client/blob/main/src/paypalSession.js): session metadata · Transforms session context into PayPal-specific metadata. · `src/paypalSession.js`

### Server runtime

Server-side validation and loader tag rendering for SDK metadata.

- [Server API](https://github.com/paypal/paypal-sdk-client/blob/main/server/index.js): server entry · Server-side exports for validating metadata and rendering loaders. · `server/index.js`
- [Unpack meta](https://github.com/paypal/paypal-sdk-client/blob/main/server/meta.jsx): validator · Validates serialized SDK metadata and rejects tampering. · `server/meta.jsx`
- [Loader tag](https://github.com/paypal/paypal-sdk-client/blob/main/server/meta.jsx): renderer · Renders the safe script tag used to bootstrap the exact SDK URL. · `server/meta.jsx`
- [Server utils](https://github.com/paypal/paypal-sdk-client/blob/main/server/util.js): server helpers · Shared server-side helpers for metadata handling and rendering. · `server/util.js`

### Tooling

Build, test, and release infrastructure.

- [Tests](https://github.com/paypal/paypal-sdk-client/blob/main/vitestSetup.js): test harness · Unit and integration coverage for client and server behavior. · `vitestSetup.js`
- [Build config](https://github.com/paypal/paypal-sdk-client/blob/main/vite.config.js): build system · Transpilation and bundling configuration for browser and server targets. · `vite.config.js`
- [Release CI](https://github.com/paypal/paypal-sdk-client/blob/main/.github/workflows/main.yml): automation · GitHub Actions and publishing workflow for validation and release. · `.github/workflows/main.yml`

### Other components

- [Package entry](https://github.com/paypal/paypal-sdk-client/blob/main/index.js): exports · Top-level package surface and bundling conventions. · `index.js`
- [SDK shim](https://github.com/paypal/paypal-sdk-client/blob/main/__sdk__.js): bundle hook · SDK-specific entry used by PayPal bundling conventions. · `__sdk__.js`

## Connections

- Package entry → Client API: exports · Package entry exposes the browser-side API.
- Package entry → Server API: exports · Package entry also exposes server-side helpers.
- Package entry → SDK shim: bundle hook · SDK bundling conventions are supported from the root surface.
- Client API → SDK meta: creates · Public API builds and exports SDK metadata helpers.
- Client API → Script loader: uses · Client API depends on script URL and loader utilities.
- Client API → API client: uses · Client API includes outbound service helpers.
- Client API → Tracking: uses · Client API includes telemetry and event tracking.
- Client API → FraudNet: uses · Client API includes fraud integration support.
- Client API → DPoP: uses · Client API includes security-binding helpers.
- SDK meta → Global state: reads · Metadata generation reads browser/global runtime context.
- SDK meta → Session state: reads · Metadata generation incorporates session state.
- SDK meta → Config: uses · Metadata depends on environment configuration.
- SDK meta → Domains: uses · Metadata includes domain and endpoint selection.
- SDK meta → PayPal session: emits · Metadata flow includes PayPal-specific session descriptors.
- Script loader → Config: resolves · Script loading depends on configuration and environment.
- Script loader → Domains: resolves · Script URLs are derived from domain selection.
- API client → GraphQL: specializes · GraphQL is a specialized outbound service path.
- Server API → Unpack meta: validates · Server entry accepts serialized metadata and validates it.
- Server API → Loader tag: renders · Server entry produces the HTML script loader tag.
- Unpack meta → Server utils: uses · Validation relies on shared server helpers.
- Loader tag → Server utils: uses · Rendering relies on shared server helpers.
- SDK meta → Unpack meta: sdkMeta · Serialized client metadata is transferred to the server boundary.
- Loader tag → Script loader: loads · Rendered tag bootstraps the exact SDK script on the child side.
- Tests → Client API: covers · Test harness exercises client behavior.
- Tests → Server API: covers · Test harness exercises server validation and rendering.
- Build config → Client API: builds · Build tooling targets the client runtime surface.
- Build config → Server API: builds · Build tooling targets the server runtime surface.
- Release CI → Tests: runs · CI executes validation and test workflows.
- Release CI → Build config: publishes · CI coordinates release and packaging workflows.
