# saasquatch/squatch-js architecture

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

- Interactive diagram: https://gitdiagram.com/saasquatch/squatch-js
- Repository: https://github.com/saasquatch/squatch-js

## Overview

Based on our analysis of the complete file tree and the README content, this project is a JavaScript SDK designed to help integrate referral widgets and related API operations into web pages and applications under the “Referral SaaSquatch Javascript SDK” banner. It’s both a toolkit for rendering web components (via custom elements such as <squatch-embed> and <squatch-popup>) and a set of APIs for operations like upserting users, tracking events, and fetching referral cookie codes.

##### Main Components
- API Layer:

- Widget Components:
– Located in “src/widgets” and “src/widgets/declarative”, this includes implementations for the EmbedWidget, PopupWidget, and DeclarativeWidgets. These components offer the custom HTML elements used in the UI.
– They are directly referenced in the README as “squatch-embed” and “squatch-popup” and have specific properties like "widget", "container", and "locale".

- Loader and Initialization:
– Files like “src/loader.js” and “src/async.ts” are part of the client-side logic to load the necessary scripts (either asynchronously or via the provided script snippet) and initialize the SDK.
– This is where the “squatch.ready” function is set up, allowing for initializing API calls or widget rendering.

- Utilities and Shared Logic:
– The “src/utils” directory contains common helper functions (for cookies, JWT decoding, DOM readiness, IO operations, UTM utilities, etc.) that support the API and widget operations.
– “src/globals.ts” and “src/types.ts” define core types and global configurations used by the SDK.

- Demo and Integration Examples:
– The “demo” folder shows how to integrate and test the SDK in a web context. This includes sample HTML (index.html), TSX examples, CSS styling, and template examples, which drive the demonstration of both widget rendering and API usage.

- Testing Infrastructure:
– The “test” directory holds the integration and unit tests, including Cucumber-based acceptance tests (features and step definitions) and traditional tests (using Jest or TDD). These indicate how components interact and confirm system behavior.

##### Relationships and Data Flows
- External Application or Web Page:
– At the outer layer, the client web page includes the SDK script either via a CDN snippet or as an npm-installed module.

- SDK Loader/Initializer:
– The loader module (from “loader.js” and “async.ts”) asynchronously loads further components and initializes the SDK once the document is ready.

- API Calls:
– When the page or widget calls “squatch.ready”, the SDK initiates API calls through the API layer (via AnalyticsApi, EventsApi, or WidgetApi) to interact with the backend services.

- Widget Rendering:
– Custom HTML elements (<squatch-embed> and <squatch-popup>) are rendered. They internally depend on the Widget components in the “src/widgets” directory to display the UI.
– These widgets may also interact with the API layer to fetch data, such as referral cookie codes or user information.

- Utility and Configuration Flow:
– Utilities ensure proper processing of cookies, decoding JWT tokens, and handling DOM events to seamlessly deliver the integration.

- Testing and Demo:
– The “demo” and “test” directories simulate integration usage and verify that each component (API calls and widget functionalities) work as expected.

##### Architectural Patterns and Design Principles
- Modularity:
– The project is organized into clearly separated concerns (API, widgets, utilities, tests) – typical of a modular, layered architecture.

- Asynchronous Initialization:
– The use of asynchronous script loading and a “ready” callback (squatch.ready) emphasizes non-blocking operations, ensuring that integration in third-party pages does not hinder overall page performance.

- Declarative Components:
– The adoption of custom elements (web components) for widgets indicates a design that separates the presentation layer from business logic.

- Extensibility:
– With both legacy API interfaces and newer declarative approaches, the design supports backward compatibility and future evolution.

##### Technologies, Frameworks, and Libraries
- JavaScript/TypeScript:
– The main implementation is in JavaScript and TypeScript.

- Web Components:
– The browser’s native support for custom elements is used for defining widget behaviors.

- Build and Automation Tools:
– Configuration files such as webpack.config.js, tsconfig.json, babel.config.js, and workflows in .github/workflows indicate the use of Babel, Webpack, and CI/CD pipelines.

- Testing Tools:
– The presence of Jest, Cucumber (features and step definitions), and test helpers in the “test” directory demonstrates a comprehensive testing framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    E["External Web Page\n(CDN/NPM Integration)"]:::external

    L["SDK Loader/Initializer\n(loader.js, async.ts)"]:::loader

    API["API Layer\n(AnalyticsApi, EventsApi,\nWidgetApi, GraphQL)"]:::api

    subgraph "Widget Components"
        S["Standard Widgets\n(EmbedWidget, PopupWidget,\nWidget, Widgets)"]:::widget
        D["Declarative Widgets\n(DeclarativeWidget, DeclarativeWidgets)"]:::widget
    end

    subgraph "Utilities & Shared Logic"
        U["Utilities\n(cookieUtils, decodeUserJwt,\ndomready, io, utmUtils, validate)"]:::util
        G["Global Config\n(globals.ts)"]:::util
        T["Types\n(types.ts)"]:::util
    end

    Demo["Demo Integration\n(index.html, generate.tsx, templates)"]:::demo

    Test["Testing Infrastructure\n(helpers, mocks, specs,\nstep_definitions, tests, tsd)"]:::test

    %% Flow connections
    E -->|"loads"| L
    L -->|"init_API_calls"| API
    L -->|"init_widget_render"| S
    L -->|"init_widget_render"| D
    S -- "triggers_API" --> API
    D -- "triggers_API" --> API
    API -- "response_data" --> S
    API -- "response_data" --> D

    U -->|"config/JWT"| API
    U -->|"cookies/DOM_ready"| S
    U -->|"cookies/DOM_ready"| D

    %% Demo and Testing integration
    E -->|"example_usage"| Demo
    Demo -->|"demonstrates"| L
    Demo -->|"demonstrates"| API
    Demo -->|"demonstrates"| S
    Demo -->|"demonstrates"| D

    Test --- E
    Test --- L
    Test --- API
    Test --- S
    Test --- D

    %% Click Events
    click L "https://github.com/saasquatch/squatch-js/blob/master/src/loader.js"
    click API "https://github.com/saasquatch/squatch-js/tree/master/src/api"
    click S "https://github.com/saasquatch/squatch-js/tree/master/src/widgets"
    click D "https://github.com/saasquatch/squatch-js/tree/master/src/widgets/declarative"
    click U "https://github.com/saasquatch/squatch-js/tree/master/src/utils"
    click G "https://github.com/saasquatch/squatch-js/blob/master/src/globals.ts"
    click T "https://github.com/saasquatch/squatch-js/blob/master/src/types.ts"
    click Demo "https://github.com/saasquatch/squatch-js/tree/master/demo"
    click Test "https://github.com/saasquatch/squatch-js/tree/master/test"

    %% Styles
    classDef external fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef loader fill:#800080,stroke:#fff,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef widget fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef demo fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef test fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
