# dxc-technology/halstack-react architecture

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

- Interactive diagram: https://gitdiagram.com/dxc-technology/halstack-react
- Repository: https://github.com/dxc-technology/halstack-react

## Overview

##### Main Components
- Core UI Component Library – This lives in the “packages/lib” folder. It contains the source code for a vast collection of React components (buttons, cards, alerts, dialogs, etc.) along with supporting utilities, context providers, and types.
- Documentation & Demo Website – Found in “apps/website”. This is a Next.js application that serves as the official documentation site. It includes pages, guides, usage examples, and live demos of the Halstack components.
- Shared Configuration & Tooling – Several configuration packages (like “packages/eslint-config” and “packages/typescript-config”) provide standards for linting, type-checking, and building. These contribute to enforcing consistency across the monorepo.
- Build, Test, and Deployment Infrastructure – The “.github/workflows” directory and “scripts” folder contain automation scripts, CI/CD configurations (for testing, publishing, chromatic visual testing, etc.), and release tools.
- Supporting Assets – This includes Storybook configurations (in packages/lib/.storybook), test files and mocks, and documentation assets (images, examples) spread throughout “apps/website/screens” and “packages/lib/src”.

##### Relationships and Interactions
- The Documentation Website consumes the UI Component Library. Users exploring the website get guided demonstrations, live examples, and usage instructions.
- The library itself is built and maintained with shared standards via ESLint and TypeScript configurations, ensuring style and type consistency.
- A suite of automated tests (both accessibility and unit tests) and visual regression tests (via Chromatic integration) are tied into the CI/CD pipeline, which is defined in GitHub workflows.
- Storybook serves as an interactive layer showcasing each component’s states and behavior.
- External services (for example, Chromatic’s visual testing platform) are integrated with the CI pipeline to verify UI changes.

##### Architectural Patterns and Design Principles
- Monorepo Architecture – The project is structured as a monorepo (managed likely with TurboRepo as indicated by “turbo.json”) where the documentation app, library code, tooling, and configuration packages coexist.
- Separation of Concerns – There is a clear division between the UI component code and the documentation/demo site. This separation helps isolate core functionality from user-facing guides.
- Component-Driven Development – Using Storybook, test cases, and React, the design system emphasizes reusable, isolated components.
- CI/CD Automation – GitHub workflows and custom scripts automate testing, linting, and publishing tasks, thereby ensuring high quality and rapid iteration.

##### Technology and Frameworks
- React and TypeScript are the foundational choices for component development.
- Next.js powers the documentation website (with pages, custom layouts, and dynamic routes).
- Storybook provides an interactive catalog of components.
- GitHub Actions, along with various automation scripts, support testing, building, and deployment.
- CSS and other styling configurations (like Prettier and ESLint) create consistency across the codebase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo"
        subgraph "Core UI Component Library"
            LIB_COMP["UI Components (src)"]:::library
            LIB_STORY["Storybook Config"]:::asset
            LIB_TEST["Tests"]:::asset
        end

        subgraph "Documentation & Demo Website"
            DOC_WEBSITE["Docs & Demo (Next.js)"]:::website
            DOC_SCREENS["Documentation Assets (Screens)"]:::asset
        end

        subgraph "Shared Config & Tooling"
            ESL["ESLint Config"]:::config
            TSC["TypeScript Config"]:::config
        end

        subgraph "Build, Test & Deployment Infrastructure"
            CICD["CI/CD Workflows"]:::cicd
            SCRIPTS["Automation Scripts"]:::cicd
        end

        EXT_EXTERNAL["Chromatic (Visual Testing)"]:::external
    end

    LIB_COMP -->|"renders"| DOC_WEBSITE
    DOC_SCREENS -->|"assets"| DOC_WEBSITE

    ESL -->|"enforces"| LIB_COMP
    ESL -->|"enforces"| DOC_WEBSITE

    TSC -->|"ensuresTypes"| LIB_COMP
    TSC -->|"ensuresTypes"| DOC_WEBSITE

    CICD -->|"triggersTests"| LIB_TEST
    CICD -->|"deploys"| DOC_WEBSITE
    SCRIPTS -->|"runsAutomation"| LIB_COMP
    SCRIPTS -->|"runsAutomation"| DOC_WEBSITE

    CICD -->|"visualTest"| EXT_EXTERNAL

    LIB_COMP -->|"includes"| LIB_STORY
    LIB_COMP -->|"includes"| LIB_TEST

    click LIB_COMP "https://github.com/dxc-technology/halstack-react/tree/master/packages/lib"
    click LIB_STORY "https://github.com/dxc-technology/halstack-react/blob/master/packages/lib/.storybook"
    click LIB_TEST "https://github.com/dxc-technology/halstack-react/tree/master/packages/lib/test"
    click DOC_WEBSITE "https://github.com/dxc-technology/halstack-react/tree/master/apps/website"
    click DOC_SCREENS "https://github.com/dxc-technology/halstack-react/tree/master/apps/website/screens"
    click ESL "https://github.com/dxc-technology/halstack-react/tree/master/packages/eslint-config"
    click TSC "https://github.com/dxc-technology/halstack-react/tree/master/packages/typescript-config"
    click CICD "https://github.com/dxc-technology/halstack-react/tree/master/.github/workflows"
    click SCRIPTS "https://github.com/dxc-technology/halstack-react/tree/master/scripts"

    classDef library fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef website fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef cicd fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef asset fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
