# patternfly/patternfly-react architecture

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

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

## Overview

1. **What this repo is**
   - This is a **Lerna-managed monorepo** for the PatternFly React design system.
   - The main output is a set of **published React packages** plus supporting packages for docs, tests, styling, icons, tokens, and developer tooling.

2. **Top-level package boundaries**
   - The repo is split into independently versioned packages such as `react-core`, `react-table`, `react-charts`, `react-icons`, `react-styles`, `react-tokens`, `react-code-editor`, `react-templates`, `react-drag-drop`, and `react-docs`.
   - `react-integration` is a separate validation surface for browser-level testing, not a library package.

3. **Core UI library (`react-core`)**
   - `packages/react-core` is the largest subsystem and contains the bulk of PatternFly components.
   - Its internal structure is organized by **components**, **layouts**, **helpers**, **styles**, **demos**, and **deprecated** APIs.
   - Most components are small compositional React primitives with dedicated tests, snapshots, and example files.

4. **Component composition model**
   - Many core components are split into a primary container plus subcomponents, contexts, and utility modules.
   - Examples include `Modal`, `Wizard`, `Tabs`, `Menu`, `Page`, `Toolbar`, `Popover`, `Dropdown`, `DataList`, `Drawer`, and `Alert`, each with supporting parts under the same folder.
   - This makes the architecture mostly **component-local**, with shared helpers used only where cross-cutting behavior is needed.

5. **Shared helpers and behavior**
   - `react-core/src/helpers` contains reusable infrastructure for cross-component concerns: focus trapping, resize observation, SSR-safe IDs, Popper positioning, keyboard handling, animation support, and OUIA metadata.
   - These helpers are the main “behavior layer” beneath UI components and are the bridge to browser APIs like layout measurement, focus management, and positioning.

6. **Layout primitives**
   - `react-core/src/layouts` contains low-level layout building blocks such as `Flex`, `Grid`, `Stack`, `Split`, `Bullseye`, `Gallery`, and `Level`.
   - These are meant to be composed by higher-level components and demos, so they act as the spacing/alignment foundation for the UI system.

7. **Styling and design tokens**
   - `react-styles` owns the CSS output and class map generation, while `react-tokens` owns the design token generation.
   - `react-core` and other packages consume these layers through generated class maps, CSS imports, and token-driven styling utilities.
   - The styling boundary is important: visual consistency comes from shared style artifacts rather than per-component ad hoc CSS.

8. **Icon system**
   - `react-icons` is a generated icon package with scripts that pull from multiple icon sources and write React icon components.
   - This package is a distinct asset pipeline: source icon definitions are transformed into reusable React components, then consumed by the UI packages.

9. **Table and charts are separate specialized engines**
   - `react-table` is a dedicated table subsystem with its own base layer, decorators, formatters, transformers, and a deprecated table implementation alongside the current one.
   - `react-charts` contains chart wrappers for both **Victory-based** and **ECharts-based** implementations, with shared chart theme utilities and component-specific examples/tests.
   - These are not just “components”; they have internal rendering and data-shaping pipelines that are more specialized than the rest of `react-core`.

10. **Template and extension packages**
   - `react-templates` provides precomposed dropdown/select patterns built on top of the core primitives.
   - `react-drag-drop` provides drag-and-drop helpers and wrappers used by higher-level components like tables and dual list selectors.
   - `react-code-editor` is a focused package for embedding and configuring code editor experiences.

11. **Docs and example generation**
   - `react-docs` is a Gatsby-based documentation site with generated content under `patternfly-docs/generated`.
   - The repo also keeps component `examples` and `demos` inside the packages, which serve as both documentation artifacts and integration examples.
   - The docs pipeline consumes these generated examples to present live component usage rather than handwritten prose alone.

12. **Testing strategy**
   - Most component packages use **unit tests plus snapshot tests** with Jest.
   - `react-integration` adds **Cypress** coverage for end-to-end browser behavior across real demo scenarios.
   - This creates a two-layer validation model: fast structural/component testing and slower runtime integration testing.

13. **Generated and deprecated surfaces**
   - Several directories are explicitly generated or machine-maintained, such as icon sources, token outputs, class maps, subpath exports, and docs artifacts.
   - Deprecated APIs are preserved under `deprecated/` in packages like `react-core` and `react-table`, which helps maintain backward compatibility while separating them from current APIs.

14. **Build, packaging, and release tooling**
   - The repo uses Yarn, Lerna, Rollup configs in individual packages, Babel/Jest/ESLint/Prettier, and multiple custom scripts under `scripts/` and `.github/`.
   - Important repo-wide scripts handle subpath export generation, single-package builds, changelog/release steps, and source transformation for CommonJS/ESM interop.
   - Architecture-wise, this means the repo is optimized for **multi-package publishing**, not a single app deploy.

15. **Overall flow**
   - Design tokens and styles are generated first, then consumed by component packages.
   - Components and layout primitives are composed into demos/examples.
   - Tests and Cypress specs validate the components against those demos.
   - Docs generation turns the same examples into published documentation content.

Main entry points: [`packages/react-core`](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core) (react-core), [`lerna.json`](https://github.com/patternfly/patternfly-react/blob/main/lerna.json) (Lerna), [`packages/react-table`](https://github.com/patternfly/patternfly-react/tree/main/packages/react-table) (react-table), [`scripts`](https://github.com/patternfly/patternfly-react/tree/main/scripts) (Scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_lerna["Lerna<br/>monorepo<br/>[lerna.json]"]
end

subgraph group_ui["UI packages"]
  node_react_core["react-core<br/>component library"]
  node_core_components["Components"]
  node_core_layouts["Layouts<br/>layout primitives"]
  node_core_helpers["Helpers<br/>behavior utilities"]
  node_core_demos["Demos<br/>example content"]
  node_core_deprecated["Deprecated<br/>legacy api"]
  node_react_styles["react-styles<br/>style pipeline"]
  node_react_tokens["react-tokens<br/>token pipeline"]
  node_react_icons["react-icons<br/>icon pipeline"]
  node_react_templates["react-templates<br/>composed patterns"]
  node_react_code_editor["react-code-editor<br/>editor package"]
end

subgraph group_data["Specialized engines"]
  node_react_table["react-table<br/>table engine"]
  node_table_base["Table base<br/>table pipeline"]
  node_table_utils["Table utils<br/>table decorators"]
  node_react_charts["react-charts<br/>chart engine"]
  node_charts_victory["Victory charts<br/>chart runtime"]
  node_charts_echarts["ECharts charts<br/>chart runtime"]
end

subgraph group_docs["Docs and validation"]
  node_react_docs["react-docs<br/>docs site"]
  node_docs_generated["Generated docs<br/>generated content"]
  node_react_integration["react-integration<br/>integration tests"]
  node_integration_app["Demo app<br/>demo runtime"]
end

subgraph group_tooling["Tooling"]
  node_scripts["Scripts<br/>repo tooling"]
end

node_lerna -->|"manages"| node_react_core
node_lerna -->|"manages"| node_react_table
node_lerna -->|"manages"| node_react_charts
node_lerna -->|"manages"| node_react_icons
node_lerna -->|"manages"| node_react_styles
node_lerna -->|"manages"| node_react_tokens
node_lerna -->|"manages"| node_react_templates
node_lerna -->|"manages"| node_react_code_editor
node_lerna -->|"manages"| node_react_docs
node_lerna -->|"manages"| node_react_integration
node_react_core -->|"contains"| node_core_components
node_react_core -->|"contains"| node_core_layouts
node_react_core -->|"contains"| node_core_helpers
node_react_core -->|"ships"| node_core_demos
node_react_core -.->|"retains"| node_core_deprecated
node_react_tokens -->|"feeds"| node_react_styles
node_react_styles -->|"styles"| node_react_core
node_react_icons -->|"consumed by"| node_react_core
node_react_templates -->|"builds on"| node_react_core
node_react_code_editor -->|"builds on"| node_react_core
node_react_table -->|"organizes"| node_table_base
node_react_table -->|"organizes"| node_table_utils
node_react_table -->|"uses"| node_react_core
node_react_charts -->|"contains"| node_charts_victory
node_react_charts -->|"contains"| node_charts_echarts
node_react_charts -->|"uses"| node_react_core
node_react_docs -->|"serves"| node_docs_generated
node_react_docs -->|"documents"| node_react_core
node_react_integration -->|"runs"| node_integration_app
node_react_integration -->|"validates"| node_react_core
node_scripts -->|"builds"| node_react_core
node_scripts -->|"builds"| node_react_table
node_scripts -->|"generates"| node_react_icons
node_scripts -->|"generates"| node_react_tokens

click node_lerna "https://github.com/patternfly/patternfly-react/blob/main/lerna.json"
click node_react_core "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core"
click node_core_components "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components"
click node_core_layouts "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/layouts"
click node_core_helpers "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/helpers"
click node_core_demos "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/demos"
click node_core_deprecated "https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/deprecated"
click node_react_styles "https://github.com/patternfly/patternfly-react/tree/main/packages/react-styles"
click node_react_tokens "https://github.com/patternfly/patternfly-react/tree/main/packages/react-tokens"
click node_react_icons "https://github.com/patternfly/patternfly-react/tree/main/packages/react-icons"
click node_react_templates "https://github.com/patternfly/patternfly-react/tree/main/packages/react-templates"
click node_react_code_editor "https://github.com/patternfly/patternfly-react/tree/main/packages/react-code-editor"
click node_react_table "https://github.com/patternfly/patternfly-react/tree/main/packages/react-table"
click node_table_base "https://github.com/patternfly/patternfly-react/tree/main/packages/react-table/src/components/Table/base"
click node_table_utils "https://github.com/patternfly/patternfly-react/tree/main/packages/react-table/src/components/Table/utils"
click node_react_charts "https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts"
click node_charts_victory "https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts/src/victory"
click node_charts_echarts "https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts/src/echarts"
click node_react_docs "https://github.com/patternfly/patternfly-react/tree/main/packages/react-docs"
click node_docs_generated "https://github.com/patternfly/patternfly-react/tree/main/packages/react-docs/patternfly-docs/generated"
click node_react_integration "https://github.com/patternfly/patternfly-react/tree/main/packages/react-integration"
click node_integration_app "https://github.com/patternfly/patternfly-react/tree/main/packages/react-integration/demo-app-ts"
click node_scripts "https://github.com/patternfly/patternfly-react/tree/main/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lerna toneBlue
class node_react_core,node_core_components,node_core_layouts,node_core_helpers,node_core_demos,node_core_deprecated,node_react_styles,node_react_tokens,node_react_icons,node_react_templates,node_react_code_editor toneAmber
class node_react_table,node_table_base,node_table_utils,node_react_charts,node_charts_victory,node_charts_echarts toneMint
class node_react_docs,node_docs_generated,node_react_integration,node_integration_app toneRose
class node_scripts toneIndigo
```

## Components

### Monorepo

Lerna-managed PatternFly React repository

- [Lerna](https://github.com/patternfly/patternfly-react/blob/main/lerna.json): monorepo · Workspace and versioning coordinator · `lerna.json`

### UI packages

Published component and asset packages

- [react-core](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core): component library · Primary PatternFly React component package · `packages/react-core`
- [Components](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components): ui components · Core component implementations and subcomponents · `packages/react-core/src/components`
- [Layouts](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/layouts): layout primitives · Flex, Grid, Stack and other composition primitives · `packages/react-core/src/layouts`
- [Helpers](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/helpers): behavior utilities · Focus, IDs, Popper, resize and browser-adjacent helpers · `packages/react-core/src/helpers`
- [Demos](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/demos): example content · Packaged demos and generated usage examples · `packages/react-core/src/demos`
- [Deprecated](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/deprecated): legacy api · Preserved legacy component surfaces · `packages/react-core/src/deprecated`
- [react-styles](https://github.com/patternfly/patternfly-react/tree/main/packages/react-styles): style pipeline · Generated CSS and class map artifacts · `packages/react-styles`
- [react-tokens](https://github.com/patternfly/patternfly-react/tree/main/packages/react-tokens): token pipeline · Design token generation and outputs · `packages/react-tokens`
- [react-icons](https://github.com/patternfly/patternfly-react/tree/main/packages/react-icons): icon pipeline · Generated React icon components from source icon sets · `packages/react-icons`
- [react-templates](https://github.com/patternfly/patternfly-react/tree/main/packages/react-templates): composed patterns · Precomposed dropdown and select patterns · `packages/react-templates`
- [react-code-editor](https://github.com/patternfly/patternfly-react/tree/main/packages/react-code-editor): editor package · Embedded code editor component package · `packages/react-code-editor`

### Specialized engines

Table and charts subsystems with their own pipelines

- [react-table](https://github.com/patternfly/patternfly-react/tree/main/packages/react-table): table engine · Specialized table rendering and behavior package · `packages/react-table`
- [Table base](https://github.com/patternfly/patternfly-react/tree/main/packages/react-table/src/components/Table/base): table pipeline · Base provider, transforms and formatters for tables · `packages/react-table/src/components/Table/base`
- [Table utils](https://github.com/patternfly/patternfly-react/tree/main/packages/react-table/src/components/Table/utils): table decorators · Decorators and transformers for table features · `packages/react-table/src/components/Table/utils`
- [react-charts](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts): chart engine · Victory and ECharts chart package · `packages/react-charts`
- [Victory charts](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts/src/victory): chart runtime · Victory-based chart components and utilities · `packages/react-charts/src/victory`
- [ECharts charts](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts/src/echarts): chart runtime · ECharts-based chart wrappers and theme helpers · `packages/react-charts/src/echarts`

### Docs and validation

Documentation site and integration testing surface

- [react-docs](https://github.com/patternfly/patternfly-react/tree/main/packages/react-docs): docs site · Gatsby-based documentation site with generated content · `packages/react-docs`
- [Generated docs](https://github.com/patternfly/patternfly-react/tree/main/packages/react-docs/patternfly-docs/generated): generated content · Machine-generated docs pages and demo content · `packages/react-docs/patternfly-docs/generated`
- [react-integration](https://github.com/patternfly/patternfly-react/tree/main/packages/react-integration): integration tests · Browser-level validation surface with Cypress and demo app · `packages/react-integration`
- [Demo app](https://github.com/patternfly/patternfly-react/tree/main/packages/react-integration/demo-app-ts): demo runtime · Vite demo application used by Cypress scenarios · `packages/react-integration/demo-app-ts`

### Tooling

Repo-wide scripts and development support

- [Scripts](https://github.com/patternfly/patternfly-react/tree/main/scripts): repo tooling · Repo-level generators, builds and release helpers · `scripts`

## Connections

- Lerna → react-core: manages · Workspace package boundary
- Lerna → react-table: manages · Workspace package boundary
- Lerna → react-charts: manages · Workspace package boundary
- Lerna → react-icons: manages · Workspace package boundary
- Lerna → react-styles: manages · Workspace package boundary
- Lerna → react-tokens: manages · Workspace package boundary
- Lerna → react-templates: manages · Workspace package boundary
- Lerna → react-code-editor: manages · Workspace package boundary
- Lerna → react-docs: manages · Workspace package boundary
- Lerna → react-integration: manages · Workspace package boundary
- react-core → Components: contains · Primary component implementations
- react-core → Layouts: contains · Foundational layout primitives
- react-core → Helpers: contains · Cross-cutting browser behavior
- react-core → Demos: ships · Examples and demo content
- react-core → Deprecated: retains · Legacy API surface
- react-tokens → react-styles: feeds · Token output informs styling artifacts
- react-styles → react-core: styles · Shared CSS and class maps consumed by components
- react-icons → react-core: consumed by · Generated icon components used across UI packages
- react-templates → react-core: builds on · Composed from core primitives
- react-code-editor → react-core: builds on · Editor package integrates with core patterns
- react-table → Table base: organizes · Rendering/provider foundation
- react-table → Table utils: organizes · Decorators, formatters and transformers
- react-table → react-core: uses · Table UI composes core primitives and styles
- react-charts → Victory charts: contains · Victory chart implementation
- react-charts → ECharts charts: contains · ECharts chart implementation
- react-charts → react-core: uses · Charts rely on shared UI and helpers
- react-docs → Generated docs: serves · Published documentation output
- react-docs → react-core: documents · Consumes examples and generated demos
- react-integration → Demo app: runs · Cypress tests exercise the demo app
- react-integration → react-core: validates · Browser-level behavior across component demos
- Scripts → react-core: builds · Package generation and release support
- Scripts → react-table: builds · Package generation and release support
- Scripts → react-icons: generates · Icon and export generation pipeline
- Scripts → react-tokens: generates · Token build and write pipeline