# white-label-loyalty/wll-react-sdk architecture

> Architecture diagram of the GitHub repository white-label-loyalty/wll-react-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/white-label-loyalty/wll-react-sdk
- Repository: https://github.com/white-label-loyalty/wll-react-sdk

## Overview

##### Project Type and Purpose
- This project is a component SDK/library specifically designed for React (and React Native) applications. Its primary goal is to provide a flexible, themeable, and composable set of UI “tiles” (covering badges, rewards, banners, etc.) that can be easily integrated into any loyalty or rewards experience.
- The README emphasizes features such as theming, mobile responsiveness, customizable navigation, and API integration via a backend proxy.

##### File Structure
- Notice the separation of concerns:
- The lib directory contains the core code including assets, components (divided into atoms, molecules, organisms), hooks, context providers (WllSdkContext, ResponsiveContext), constants, types, mocks, unit tests, and utility functions.
- The docs directory holds both user documentation and sample components to illustrate the capabilities.
- There are configuration files for build tools (Babel, Rollup, Webpack), testing (Jest), and continuous integration (GitHub Actions workflows), which indicates a robust development and release pipeline.
- This structure also confirms that the project follows a modular, atomic design pattern for UI development.

##### Key Components
a. Core UI Component Library (located in lib/components):
- Molecules (combinations like Carousel, SectionHeader, etc.)
- Organisms (more complex composites like BadgeTile, ContentTile, RewardTile, etc.)
b. Context Providers and Hooks:
- WllSdkContext: likely for global settings like theming or navigation.
- ResponsiveContext and related hooks (useResponsive, useTileSize) hint at responsive design handling.
c. Utility and Helper Modules:
- Functions found under lib/utils, which provide API helpers, context helpers, theme helpers, etc.
d. Configuration, Build, and Testing Infrastructure:
- Build configuration files (babel.config.js, rollup.config.js, webpack.config.js)
- Testing setup (jest.config.js, lib/unit-tests, test utilities)
- Documentation and Storybook configuration (storybook folder, docs, and .vitepress config)

##### Relationships and Interactions
- How the UI components (organized via the atomic design hierarchy) form the basis of the SDK and are wrapped by context providers that supply them with theming and navigation capabilities.
- How custom hooks and utility modules support these components, enabling dynamic behavior and responsive design.
- Build/test pipeline as a side module showing CI/CD configurations (e.g., GitHub workflows, husky hooks for commit linting, etc.), ensuring code quality and version management.

##### Architectural Patterns and Design Principles
- Atomic Design pattern, separating UI into atoms, molecules, and organisms.
- Separation of concerns; UI components are decoupled from context management (for theming and responsiveness) and utility functions.
- That extensibility is a core design principle—developers can integrate their own navigation or network layers using the provided context and hooks.

- “UI Component Library” (with its internal atomic breakdown)
- “Context & Hooks” (for theming and responsiveness)
- “Utilities & Helpers”
- “Build/Test/Documentation Tools”

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Component Library"
        UI1["Atoms"]:::uiComponents
        UI2["Molecules"]:::uiComponents
        UI3["Organisms"]:::uiComponents
    end

    subgraph "Context & Hooks"
        CTX1["WllSdkContext"]:::context
        CTX2["ResponsiveContext"]:::context
        HOOKS["Hooks & Responsive Utilities"]:::context
    end

    subgraph "Utilities & Helpers"
        UTILS["Utility & Helper Modules"]:::utilities
    end

    subgraph "Build/Test/Documentation"
        TEST["Testing Infrastructure"]:::config
        BUILD["Build & Release Configuration"]:::config
        DOCS["Documentation & Storybook Config"]:::config
    end

    %% Relationships from Context Providers to UI Components
    CTX1 -->|"providesTheme"| UI1
    CTX1 -->|"providesTheme"| UI2
    CTX1 -->|"providesTheme"| UI3
    CTX2 -->|"handlesResponsiveness"| UI1
    CTX2 -->|"handlesResponsiveness"| UI2
    CTX2 -->|"handlesResponsiveness"| UI3
    HOOKS -->|"injectsBehavior"| UI1
    HOOKS -->|"injectsBehavior"| UI2
    HOOKS -->|"injectsBehavior"| UI3

    %% Relationships from Utilities to UI Components
    UTILS -->|"supports"| UI1
    UTILS -->|"supports"| UI2
    UTILS -->|"supports"| UI3

    %% Relationships from Build/Test/Documentation to UI Components
    TEST -->|"ensuresQuality"| UI1
    TEST -->|"ensuresQuality"| UI2
    TEST -->|"ensuresQuality"| UI3
    BUILD -->|"buildsAndReleases"| UI1
    BUILD -->|"buildsAndReleases"| UI2
    BUILD -->|"buildsAndReleases"| UI3
    DOCS -->|"guidesUsage"| UI1
    DOCS -->|"guidesUsage"| UI2
    DOCS -->|"guidesUsage"| UI3

    %% Click Events
    click UI1 "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/components/atoms"
    click UI2 "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/components/molecules"
    click UI3 "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/components/organisms"
    click CTX1 "https://github.com/white-label-loyalty/wll-react-sdk/blob/main/lib/context/WllSdkContext.tsx"
    click CTX2 "https://github.com/white-label-loyalty/wll-react-sdk/blob/main/lib/context/ResponsiveContext.tsx"
    click HOOKS "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/hooks"
    click UTILS "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/utils"
    click TEST "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/lib/unit-tests"
    click BUILD "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/.github/workflows"
    click DOCS "https://github.com/white-label-loyalty/wll-react-sdk/tree/main/docs"

    %% Styles
    classDef uiComponents fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef context fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utilities fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
