# zendeskgarden/react-components architecture

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

- Interactive diagram: https://gitdiagram.com/zendeskgarden/react-components
- Repository: https://github.com/zendeskgarden/react-components

## Overview

##### Project type and purpose
- This is a monorepo-based React component library (Garden design system) maintained via Lerna and Yarn workspaces.
- It publishes dozens of standalone UI packages (buttons, forms, datepickers, etc.) under the single repository.
- Key features: multi-package build/publish, shared theming, Storybook demos, Jest tests, and centralized scripts/config.

##### File structure
- Top-level:
- .github, docs, utils, config files (babel.config.js, lerna.json, tsconfig.json, CI workflows)
- package.json / package-lock.json / Yarn workspace config under lerna.json
- packages/…: each folder is a component package with:
- package.json (defines name, version, peerDependencies)
- src/ (elements, styled, utils, types)
- demo/ (Storybook stories and MDX)
- tsconfig.build.json, tests (.spec.tsx)
- utils/: shared build and deploy scripts (rollup config, shell scripts)
- docs/: ADRs, API reference, migration guides, versioning, development guidelines
- .storybook/: global Storybook configuration for demos
- CI/CD via .github/workflows invoking build, lint, test, deploy

##### Insights from README
- Confirms multi-package approach: “React components are packaged and published individually”
- Shows package listing (accordions, avatars, … typography)
- References ThemeProvider from @zendeskgarden/react-theming as core dependency
- Encourages Storybook and external docs for usage and development

- Monorepo Root
– Lerna & Yarn Workspaces
– Shared config (TS, Babel, ESLint, Prettier)
– CI/CD pipelines (GitHub Actions)
– Docs & ADRs
– Utils (build, test, deploy scripts)
- Packages workspace
– Each package (e.g. react-buttons, react-forms)
– Underlying src layers: Elements → Styled components → Utilities → Types
– Demo layer (Storybook stories)
- Core @zendeskgarden/react-theming
- External dependencies: React, ReactDOM, styled-components (or Emotion), Lodash, etc.
- Consumers: downstream applications or other packages that import components

- Monorepo Root → initializes and orchestrates packages via Lerna
- Packages ← share configs & scripts from root utils
- Storybook config ← packages/demo feed into .storybook to render UI
- CI/CD → runs build/test/lint for all packages → publishes to npm registry

c. Architectural patterns/design principles:
- Monorepo with Lerna & Yarn Workspaces for version and dependency management
- Package-per-component for granular releases
- Separation of concerns:
– “elements” (React logic/UI)
– “styled” (CSS-in-JS definitions)
– “utils” (hooks, reducers, context)
– “types” (TypeScript definitions)
- Shared tooling (Babel, TypeScript, ESLint, Storybook) to enforce consistency
- Demo layer leveraging Storybook for visual regression and documentation
- ADRs capture key technical decisions

d. Relevant technologies/frameworks:
- React & ReactDOM
- TypeScript
- Babel & Rollup (build pipeline)
- Jest & Testing Library (unit tests)
- Storybook (component demos)
- GitHub Actions (CI/CD)
- Lerna & Yarn Workspaces (monorepo)
- CSS-in-JS library (styled-components or equivalent)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo Root"
        Root["Monorepo Root\n(Lerna & Yarn Workspaces)"]:::root
    end

    subgraph "Shared Config"
        Config["Shared Config\n(TS, Babel, ESLint, Prettier)"]:::config
    end

    subgraph "CI/CD Pipelines"
        CICD(("CI/CD Pipelines\n(GitHub Actions)")):::cicd
    end

    subgraph "Docs & ADRs"
        Docs(("Docs & ADRs")):::docs
    end

    subgraph "Shared Utilities"
        Utils["Shared Utilities\n(build, test, deploy scripts)"]:::utils
    end

    subgraph "Global Storybook Config"
        SB["Global Storybook Config"]:::sb
    end

    subgraph "Packages Workspace"
        Packages["Packages Workspace"]:::workspace

        subgraph "Core Theming Package"
            Theming["@zendeskgarden/react-theming"]:::package
        end

        subgraph "Component: Buttons"
            Buttons["Buttons Package"]:::package
        end

        subgraph "Component: Forms"
            Forms["Forms Package"]:::package
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        React[("React")]:::external
        ReactDOM[("ReactDOM")]:::external
        StyledComp[("styled-components / Emotion")]:::external
        Lodash[("Lodash")]:::external
    end

    %% Connections
    Root -->|"orchestrates"| Packages
    Root --> Config
    Root --> CICD
    Root --> Docs
    Root --> Utils
    Root --> SB

    Config -->|"shares configs"| Packages
    Utils -->|"provides scripts"| Packages

    Packages -->|"contains"| Theming
    Theming -->|"peer-depends"| Buttons
    Theming -->|"peer-depends"| Forms

    Buttons -->|"feeds demos"| SB
    Forms -->|"feeds demos"| SB

    CICD -->|"runs build/test/publish"| Packages

    React -->|"peerDependency"| Buttons
    React -->|"peerDependency"| Forms
    StyledComp -->|"peerDependency"| Buttons
    StyledComp -->|"peerDependency"| Forms

    %% Click Events
    click Root "https://github.com/zendeskgarden/react-components/blob/main/lerna.json"
    click Root "https://github.com/zendeskgarden/react-components/blob/main/package.json"
    click Root "https://github.com/zendeskgarden/react-components/blob/main/tsconfig.json"
    click Root "https://github.com/zendeskgarden/react-components/blob/main/package-lock.json"

    click Config "https://github.com/zendeskgarden/react-components/blob/main/babel.config.js"
    click Config "https://github.com/zendeskgarden/react-components/blob/main/eslint.config.mjs"
    click Config "https://github.com/zendeskgarden/react-components/blob/main/.prettierrc"
    click Config "https://github.com/zendeskgarden/react-components/blob/main/.stylelintrc"

    click CICD "https://github.com/zendeskgarden/react-components/blob/main/.github/workflows/ci.yaml"
    click CICD "https://github.com/zendeskgarden/react-components/blob/main/.github/workflows/pr.yaml"

    click Docs "https://github.com/zendeskgarden/react-components/tree/main/docs/adrs/"
    click Docs "https://github.com/zendeskgarden/react-components/blob/main/docs/api.md"
    click Docs "https://github.com/zendeskgarden/react-components/blob/main/docs/development.md"
    click Docs "https://github.com/zendeskgarden/react-components/blob/main/docs/versioning.md"

    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/build/rollup.config.js"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/scripts/build.sh"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/scripts/deploy.mjs"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/scripts/new.mjs"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/scripts/tag.mjs"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/test/jest.config.js"
    click Utils "https://github.com/zendeskgarden/react-components/blob/main/utils/test/jest.setup.js"

    click SB "https://github.com/zendeskgarden/react-components/blob/main/.storybook/main.js"
    click SB "https://github.com/zendeskgarden/react-components/blob/main/.storybook/preview.js"
    click SB "https://github.com/zendeskgarden/react-components/blob/main/.storybook/manager.js"

    click Packages "https://github.com/zendeskgarden/react-components/tree/main/packages/"
    click Theming "https://github.com/zendeskgarden/react-components/tree/main/packages/theming/src/"

    click Buttons "https://github.com/zendeskgarden/react-components/blob/main/packages/buttons/src/elements/Button.tsx"
    click Forms "https://github.com/zendeskgarden/react-components/blob/main/packages/forms/src/elements/Input.tsx"

    %% Styles
    classDef root fill:#f9f,stroke:#333,stroke-width:2px
    classDef config fill:#afa,stroke:#333,stroke-width:1px
    classDef cicd fill:#ff9,stroke:#333,stroke-width:2px
    classDef docs fill:#ddf,stroke:#333,stroke-width:1px
    classDef utils fill:#fcf,stroke:#333,stroke-width:1px
    classDef sb fill:#cdf,stroke:#333,stroke-width:1px
    classDef workspace fill:#eee,stroke:#333,stroke-width:2px
    classDef package fill:#fff,stroke:#666,stroke-dasharray: 5 5
    classDef external fill:#eef,stroke:#666,stroke-width:1px,stroke-dasharray:4 2
```
