# pegasystems/constellation-ui-gallery architecture

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

- Interactive diagram: https://gitdiagram.com/pegasystems/constellation-ui-gallery
- Repository: https://github.com/pegasystems/constellation-ui-gallery

## Overview

##### Project type and purpose
- This is a front-end component library and documentation site built with React, TypeScript, and Storybook. It provides ready-to-use “Constellation DX” UI components for the Pega Platform, along with tooling to build, test, bundle, and publish them.

##### File structure
- Top-level directories and files:
- `.devcontainer/` – VS Code Dev Container configuration
- `.github/workflows/` – CI/CD pipelines (GitHub Actions)
- `src/` – React components, MDX docs, Storybook stories
- `storybook/` – Storybook configuration and theming
- `package.json`, `babel.config.js`, `tsconfig*.json` – build, lint, test configuration
- `tasks.config.json` – Constellation DX CLI publishing config
- Build and test scripts are in `package.json` (start, build, lint, test, publish).

##### README for additional insights
- The README outlines local development (npm install, `npm run start` for Storybook), linting, unit tests (Jest), end-to-end tests (Playwright), production build, and publishing to a Pega server via Constellation DX CLI.

##### Main components and their interactions
a. Source Code Repository (GitHub)
b. Developer Environment
- VS Code with Dev Container
- Node.js, npm
- React/TypeScript code in `src/`
c. Storybook
- Serves interactive component gallery (`npm run start`)
- Static build (`npm run build-storybook`)
d. Testing
- Unit tests via Jest
- E2E tests & accessibility checks via Playwright against Storybook
e. Build & Packaging
- Babel + TypeScript → transpile components
- `npm run buildAllComponents` → bundles ready for consumption
f. Publishing
- Constellation DX CLI: `npm run authenticate` → auth to Pega Platform
- `npm run publishAll` → upload RAP file containing components to Pega server
g. CI/CD (GitHub Actions)
- Validate PRs, run lint/test, build Storybook, deploy docs to GitHub Pages, run security scans

##### Architectural patterns and design principles
- Separation of concerns:
- Presentation components under `src/components/*`
- Documentation in MDX alongside each component
- Configuration and demos isolated in per-component folders
- Pipeline-as-code: workflows defined in `.github/workflows`
- Containerized development: `.devcontainer` for reproducible IDE setup

##### Detail without over-fragmentation
- Component is clearly named (e.g., “Constellation DX CLI”, “Storybook Server”, “GitHub Pages”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Workstation"
        DevEnv["VS Code Dev Container<br/>Node.js & npm"]:::dev
    end
    DevEnv -->|push code| GitHub

    %% Source Control
    GitHub["GitHub (Source Repo)"]:::repo
    GitHub -->|trigger workflows| CI

    %% CI/CD Pipelines
    subgraph "CI/CD (GitHub Actions)"
        Validate["Validate PR (Lint & Unit Test)"]:::cicd
        DeployPages["Deploy Docs to GitHub Pages"]:::cicd
        SecurityScan["Mend Security Scan"]:::cicd
    end
    CI[CI/CD Runner]:::cicd_engine
    CI --> Validate
    CI --> DeployPages
    CI --> SecurityScan
    Validate -->|build storybook| StoryBuild
    DeployPages -->|deploy static site| GitHubPages
    SecurityScan -->|report| GitHub

    GitHubPages["GitHub Pages"]:::external

    %% Local Development
    subgraph "Local Development"
        StorybookLocal["Storybook Server<br/>(npm run start)"]:::run
    end
    DevEnv -->|npm run start| StorybookLocal

    %% Testing
    subgraph "Testing"
        Playwright["Playwright E2E & Accessibility"]:::test
        Jest["Jest Unit Tests"]:::test
    end
    StorybookLocal -->|run tests| Playwright
    DevEnv -->|npm test| Jest

    %% Build & Packaging
    subgraph "Build & Packaging"
        Transpile["Babel + TypeScript Transpile"]:::build
        Bundle["Bundle Components"]:::build
        StoryBuild["Build Storybook Static"]:::build
        RAP["RAP Package"]:::build
    end
    DevEnv -->|npm run buildAllComponents| Bundle
    DevEnv -->|npm run build-storybook| StoryBuild
    Bundle --> RAP

    %% Publishing
    subgraph "Publishing"
        DXCLI["Constellation DX CLI"]:::publish
        Pega["Pega Platform (Server)"]:::external
    end
    DXCLI -->|authenticate & publishAll| Pega
    RAP --> DXCLI

    CI -->|publish docs| GitHubPages
    CI -->|publish RAP| Pega

    %% Configurations & Libraries
    subgraph "Configurations & Code"
        subgraph "Storybook Config & Themes"
            SBMain[".storybook/main.ts"]:::config
            SBManager[".storybook/manager.ts"]:::config
            SBPreview[".storybook/preview.tsx"]:::config
            SBTheme[".storybook/theme.ts"]:::config
            Flame[".storybook/FlameTheme.json"]:::config
            Honey[".storybook/HoneyFlowerTheme.json"]:::config
            Mantis[".storybook/MantisTheme.json"]:::config
        end
        subgraph "React/TypeScript Components"
            Components["src/components/"]:::library
        end
        subgraph "Documentation (MDX)"
            GS["src/GettingStarted.mdx"]:::docs
            Lib["src/Libraries.mdx"]:::docs
            Sup["src/Support.mdx"]:::docs
            CompDocs["src/components/**/Docs.mdx"]:::docs
        end
        subgraph "Stories & Demos"
            DemoStories["src/components/**/demo.stories.tsx"]:::docs
        end
        subgraph "Tests"
            JestConfig["jest.config.js"]:::config
            SetupTests["setupTests.ts"]:::config
            DemoTest["src/components/**/demo.test.tsx"]:::test
            PlayRunner[".storybook/test-runner.ts"]:::test
        end
        subgraph "Build Config"
            BabelCfg["babel.config.js"]:::config
            TSCfg["tsconfig.json"]:::config
            TSBuildCfg["tsconfig.build.json"]:::config
        end
        subgraph "Publishing Config"
            Tasks["tasks.config.json"]:::config
        end
        subgraph "Package Management"
            Pkg["package.json"]:::config
            PkgLock["package-lock.json"]:::config
        end
    end

    %% Click Events
    click DevEnv "https://github.com/pegasystems/constellation-ui-gallery/tree/master/.devcontainer/"
    click Validate "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.github/workflows/validatepr.yaml"
    click DeployPages "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.github/workflows/deploy-github-pages.yaml"
    click SecurityScan "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.github/workflows/mend-scan.yml"
    click SBMain "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/main.ts"
    click SBManager "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/manager.ts"
    click SBPreview "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/preview.tsx"
    click SBTheme "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/theme.ts"
    click Flame "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/FlameTheme.json"
    click Honey "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/HoneyFlowerTheme.json"
    click Mantis "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/MantisTheme.json"
    click Components "https://github.com/pegasystems/constellation-ui-gallery/tree/master/src/components/"
    click GS "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/GettingStarted.mdx"
    click Lib "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/Libraries.mdx"
    click Sup "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/Support.mdx"
    click CompDocs "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/components/**/Docs.mdx"
    click DemoStories "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/components/**/demo.stories.tsx"
    click JestConfig "https://github.com/pegasystems/constellation-ui-gallery/blob/master/jest.config.js"
    click SetupTests "https://github.com/pegasystems/constellation-ui-gallery/blob/master/setupTests.ts"
    click DemoTest "https://github.com/pegasystems/constellation-ui-gallery/blob/master/src/components/**/demo.test.tsx"
    click PlayRunner "https://github.com/pegasystems/constellation-ui-gallery/blob/master/.storybook/test-runner.ts"
    click BabelCfg "https://github.com/pegasystems/constellation-ui-gallery/blob/master/babel.config.js"
    click TSCfg "https://github.com/pegasystems/constellation-ui-gallery/blob/master/tsconfig.json"
    click TSBuildCfg "https://github.com/pegasystems/constellation-ui-gallery/blob/master/tsconfig.build.json"
    click Tasks "https://github.com/pegasystems/constellation-ui-gallery/blob/master/tasks.config.json"
    click Pkg "https://github.com/pegasystems/constellation-ui-gallery/blob/master/package.json"
    click PkgLock "https://github.com/pegasystems/constellation-ui-gallery/blob/master/package-lock.json"

    %% Classes
    classDef dev fill:#D6E9FF,stroke:#3273DC,color:#0A3D62
    classDef repo fill:#FFE4B5,stroke:#FFA500,color:#8B4513
    classDef cicd fill:#E0F7FA,stroke:#00ACC1,color:#006064
    classDef cicd_engine fill:#B2EBF2,stroke:#00838F,color:#004D40
    classDef external fill:#F0F0F0,stroke:#CCCCCC,color:#333333
    classDef run fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef test fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef build fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef publish fill:#FBE9E7,stroke:#D84315,color:#BF360C
    classDef config fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef library fill:#FFFDE7,stroke:#FBC02D,color:#F57F17
    classDef docs fill:#E1F5FE,stroke:#039BE5,color:#01579B
```
