# pegasystems/web-components-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/pegasystems/web-components-sdk
- Repository: https://github.com/pegasystems/web-components-sdk

## Overview

Based on our review of the complete file tree and the README file, this project is the Web Components SDK. Its purpose is to enable Pega customers to create digital experience (DX) components by bridging Pega’s ConstellationJS Engine APIs with a custom, Lion-based design system. In other words, it is a front-end SDK for building replaceable and extensible web components that are used on Pega Infinity applications.

##### Main Components
- SDK Core & Bridge Layer:
- “constellation” directory and the “bridge” folder inside “src”. These folders form the core connection between the Constellation APIs and the SDK, enabling integration with Pega Infinity.

- UI Components (Design System):
- One large, modular segment is the “src/components” folder, which houses a variety of sub-folders: fields, templates, widgets, forms, and design system extensions. Each subfolder includes its own styles, configuration files, and code.
▪ Form & Field Components (e.g., AutoComplete, Checkbox, Date, TextInput)
▪ Template Components (e.g., CaseView, ListView, TwoColumn)
▪ Widget Components (e.g., AppAnnouncement, CaseOperator, FileUtility)
▪ Extension Components (under designSystemExtension)
- That these components are built with LitElement, lit-html, and upgraded Lion web components.

- Sample Applications:
- The “src/samples” directory contains sample implementations (Embedded, FullPortal, SimplePortal, etc.) which demonstrate how the SDK is integrated into real-world use cases.

- Helpers, Utilities & Configuration:
- The “src/helpers” folder encapsulates utility functions, formatters, and support code that assist the UI components.

- Build and Testing Infrastructure:
- Also, include the “tests” directory—a set of automated tests (end-to-end tests with Playwright and other integration tests) that validate the SDK’s functionality.

##### Relationships and Interactions
- The “Bridge Layer” interacts with the Constellation API, passing data to and from the “UI Components.”
- The “UI Components” consume helper functions and utilities from the “helpers” folder.
- Sample applications illustrate how the SDK’s components are instantiated and interact with the Pega backend.

##### Architectural Patterns and Design Principles
- Modularity and reusability: The project is highly componentized, grouping similar UI and form elements together.
- Layered Architecture: Illustrate a separation between the presentation layer (UI components), the integration/bridge layer (connecting to Pega APIs), and the configuration/test/build layers.

##### Relevant Technologies and Frameworks
- Frontend Libraries: LitElement, lit-html.
- Design System: Lion web components (now using @lion/ui).
- Build Tools: Webpack, Babel.
- Testing: Playwright for e2e tests.
- CI/CD: GitHub Actions workflows as evidenced in the “.github/workflows” folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Integration Layer"
        CI["Constellation API Integration"]:::integration
        BI["Bridge Implementation"]:::integration
    end

    subgraph "UI Components (Design System)"
        UIC["UI Components"]:::ui
        FF["Form & Field Components"]:::ui
        TC["Template Components"]:::ui
        WC["Widget Components"]:::ui
        EC["Extension Components"]:::ui
    end

    subgraph "Usage Examples / Client Implementations"
        SA["Sample Applications"]:::sample
    end

    subgraph "Helpers, Utilities & Configuration"
        HU["Helper Functions & Utilities"]:::helpers
        CF1["package.json"]:::config
        CF2["babel.config.js"]:::config
        CF3["webpack.config.js"]:::config
        CF4["tsconfig.json"]:::config
        CF5["sdk-config.json"]:::config
        GS1["sdkStyles.css"]:::config
        GS2["sdkCssVars.css"]:::config
    end

    subgraph "Build & Testing Infrastructure"
        CICD["CI/CD Pipelines"]:::build
        AT["Automated Tests"]:::build
    end

    subgraph "External Dependencies"
        LE["LitElement & lit-html"]:::external
        LW["Lion Web Components"]:::external
        Pega["Pega Infinity API"]:::external
    end

    %% Data Flow Connections
    BI -->|"bridges"| CI
    BI -->|"suppliesData"| UIC
    UIC -->|"composedOf"| FF
    UIC -->|"composedOf"| TC
    UIC -->|"composedOf"| WC
    UIC -->|"composedOf"| EC
    HU -->|"assists"| UIC
    CF1 -->|"configures"| UIC
    CF2 -->|"configures"| UIC
    CF3 -->|"configures"| UIC
    CF4 -->|"configures"| UIC
    CF5 -->|"configures"| UIC
    GS1 -->|"styles"| UIC
    GS2 -->|"styles"| UIC
    SA -->|"demonstrates"| UIC
    UIC -->|"builtWith"| LE
    UIC -->|"builtWith"| LW
    BI -->|"integrates"| Pega
    CICD -->|"deploys"| UIC
    AT -->|"validates"| UIC

    %% Click Events
    click CI "https://github.com/pegasystems/web-components-sdk/tree/main/constellation"
    click BI "https://github.com/pegasystems/web-components-sdk/tree/main/src/bridge"
    click FF "https://github.com/pegasystems/web-components-sdk/tree/main/src/components/fields"
    click TC "https://github.com/pegasystems/web-components-sdk/tree/main/src/components/templates"
    click WC "https://github.com/pegasystems/web-components-sdk/tree/main/src/components/widgets"
    click EC "https://github.com/pegasystems/web-components-sdk/tree/main/src/components/designSystemExtension"
    click SA "https://github.com/pegasystems/web-components-sdk/tree/main/src/samples"
    click HU "https://github.com/pegasystems/web-components-sdk/tree/main/src/helpers"
    click CF1 "https://github.com/pegasystems/web-components-sdk/blob/main/package.json"
    click CF2 "https://github.com/pegasystems/web-components-sdk/blob/main/babel.config.js"
    click CF3 "https://github.com/pegasystems/web-components-sdk/blob/main/webpack.config.js"
    click CF4 "https://github.com/pegasystems/web-components-sdk/blob/main/tsconfig.json"
    click CF5 "https://github.com/pegasystems/web-components-sdk/blob/main/sdk-config.json"
    click GS1 "https://github.com/pegasystems/web-components-sdk/blob/main/assets/css/sdkStyles.css"
    click GS2 "https://github.com/pegasystems/web-components-sdk/blob/main/assets/css/sdkCssVars.css"
    click CICD "https://github.com/pegasystems/web-components-sdk/tree/main/.github/workflows"
    click AT "https://github.com/pegasystems/web-components-sdk/tree/main/tests"

    %% Styles
    classDef integration fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef ui fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef sample fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef helpers fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#333,stroke-width:2px;
```
