# mr-harishv/carbon-labs architecture

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

- Interactive diagram: https://gitdiagram.com/mr-harishv/carbon-labs
- Repository: https://github.com/mr-harishv/carbon-labs

## Overview

1. This is a monorepo for Carbon Labs: a set of independently published UI packages, not a single application. The core architectural idea is “many small component packages” with their own source, tests, docs, Storybook stories, and package metadata.

2. The repo is split by runtime and delivery model:
   - `packages/react` for React component packages
   - `packages/web-components` for custom elements / web components
   - `packages/primitives` for headless/shared logic used by components
   - `packages/utilities` for cross-package helper functions
   - `packages/vscode-snippets` and `packages/vscode-snippets-extension` for editor tooling
   - `tools/create` and repo-level `tools/*` for scaffolding and repo maintenance

3. The React side is organized as one package per component under `packages/react/src/components/<ComponentName>`. Each component typically contains its implementation, styles, Storybook stories/MDX docs, tests, telemetry metadata, and a package entry point. Larger composites like `UIShell`, `PlaneStack3D`, and `MDXComponents` have internal subcomponent trees and shared helpers, but still publish as single packages.

4. The Web Components side follows a similar “one package per component” model under `packages/web-components/src/components/<name>`, but with a web-component-specific structure: source files, template files, SCSS, generated/custom-element entrypoints, and sometimes service/adaptor layers. This package also contains component-level React wrappers for some components, showing a bridge boundary for React consumers.

5. `packages/primitives` contains non-visual logic and state machines, most clearly the date-picker primitive. This package is the headless layer: state transitions, keyboard handling, click-outside handling, and date/temporal utilities live here so UI packages can reuse behavior without reimplementing it.

6. `packages/utilities` is the smallest shared boundary: generic helpers such as prefixing/settings utilities that are imported by multiple packages. It exists to keep common runtime behavior out of individual components and avoid duplication across the monorepo.

7. The repo includes multiple consumer/demo surfaces in `examples/react` and `examples/web-components`. These are separate Vite apps for validating components in realistic app contexts; they act as integration examples rather than production applications. They also reflect the two supported consumption models: React import and browser-native custom elements.

8. Storybook is a major architectural layer, not just documentation. There is root Storybook configuration plus per-package Storybook configs, templates, and welcome screens. Stories and MDX docs are part of the source tree and are used to visualize component states, edge cases, and usage guidance before publishing.

9. Testing is layered per package:
   - unit/snapshot tests alongside each component
   - web-component browser tests using `web-test-runner`
   - some UI-level/browser automation configuration at the repo root via Playwright
   This keeps verification close to each package boundary while still supporting end-to-end checks where needed.

10. The repo is built and released through package-specific build tasks and GitHub Actions. Workflows cover CI, PR checks, releases, canary/CDN publishing, Storybook publishing, and automerge. `netlify.toml` and the Storybook publish workflow show that the docs/demo surface is deployed separately from package artifacts.

11. There are two significant “composite system” areas worth diagramming specially:
   - `UIShell` / `global-header`, which combine many internal subcomponents, runtime scripts, context providers, and accessibility/keyboard helpers
   - `ThemeSettings` / `StylePicker`, which manage shared theme state and expose UI controls that affect global appearance
   These are more like feature subsystems than single widgets.

12. The repo also has a generation/scaffolding pipeline. `tools/create` and `packages/*/tasks/generate` create new component packages from templates, inject metadata, and standardize structure. That means new components enter the architecture through a controlled scaffold, not ad hoc folder creation.

13. A notable cross-cutting concern is telemetry and governance: many components include `telemetry.yml`, and the repo carries contribution, release, and license automation. That makes package metadata, docs, and compliance part of the architecture rather than afterthoughts.

14. For a diagram, the key flow is: scaffold/template → component package source → stories/tests/docs → package build → publish to npm/CDN and Storybook → consume from examples or downstream apps. The main boundaries are React vs Web Components, visual components vs shared primitives/utilities, and source/runtime vs documentation/release infrastructure.

Main entry points: [`packages/react`](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react) (React UI), [`packages/web-components`](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components) (Web components), [`.github/workflows`](https://github.com/mr-harishv/carbon-labs/blob/main/.github/workflows) (CI & release), [`.storybook`](https://github.com/mr-harishv/carbon-labs/blob/main/.storybook) (Storybook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_react["React packages"]
  node_react_packages["React UI<br/>package family"]
  node_react_uishell["UIShell<br/>react composite"]
  node_react_theming["ThemeSettings<br/>react system"]
  node_react_composites["Other React comps<br/>react packages"]
  node_react_mdx["MDX Components<br/>react docs ui"]
  node_react_plane3d["PlaneStack3D<br/>react visualization"]
end

subgraph group_group_web["Web components"]
  node_web_packages["Web components<br/>package family"]
  node_web_chat["Chat<br/>web component suite"]
  node_web_global_header["GlobalHeader<br/>web composite"]
  node_web_style_picker["StylePicker<br/>web composite"]
  node_web_date_picker["DatePicker<br/>web bridge"]
end

subgraph group_group_shared["Shared layers"]
  node_primitives["Primitives<br/>headless package"]
  node_utilities["Utilities<br/>shared helpers"]
end

subgraph group_group_tooling["Tooling"]
  node_react_generator["React generator<br/>scaffold task"]
  node_web_generator["Web generator<br/>scaffold task"]
  node_storybook_root["Storybook<br/>docs runtime<br/>[.storybook]"]
  node_ci_release["CI & release<br/>automation<br/>[workflows]"]
end

subgraph group_group_examples["Examples"]
  node_examples_react["React examples<br/>vite demos"]
  node_examples_web["Web examples<br/>vite demos"]
end

node_repo_root["Carbon Labs<br/>monorepo"]

node_repo_root -->|"contains"| node_react_packages
node_repo_root -->|"contains"| node_web_packages
node_repo_root -->|"contains"| node_primitives
node_repo_root -->|"contains"| node_utilities
node_repo_root -->|"docs layer"| node_storybook_root
node_repo_root -->|"automation"| node_ci_release
node_repo_root -->|"contains"| node_examples_react
node_repo_root -->|"contains"| node_examples_web
node_react_packages -->|"includes"| node_react_uishell
node_react_packages -->|"includes"| node_react_theming
node_react_packages -->|"includes"| node_react_plane3d
node_react_packages -->|"includes"| node_react_mdx
node_react_packages -->|"includes"| node_react_composites
node_react_generator -->|"scaffolds"| node_react_packages
node_web_packages -->|"includes"| node_web_chat
node_web_packages -->|"includes"| node_web_global_header
node_web_packages -->|"includes"| node_web_style_picker
node_web_packages -->|"includes"| node_web_date_picker
node_web_generator -->|"scaffolds"| node_web_packages
node_react_plane3d -->|"reuses"| node_primitives
node_react_uishell -->|"reuses"| node_utilities
node_react_theming -->|"reuses"| node_utilities
node_web_global_header -->|"reuses"| node_utilities
node_web_date_picker -->|"adapts"| node_primitives
node_web_style_picker -.->|"mirrors"| node_react_theming
node_storybook_root -->|"documents"| node_react_packages
node_storybook_root -->|"documents"| node_web_packages
node_ci_release -->|"publishes"| node_storybook_root
node_ci_release -->|"releases"| node_react_packages
node_ci_release -->|"releases"| node_web_packages
node_examples_react -->|"consumes"| node_react_packages
node_examples_web -->|"consumes"| node_web_packages

click node_react_packages "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react"
click node_react_uishell "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/UIShell"
click node_react_theming "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/ThemeSettings"
click node_react_composites "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components"
click node_react_mdx "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/MDXComponents"
click node_react_plane3d "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/PlaneStack3D"
click node_react_generator "https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/tasks/generate"
click node_primitives "https://github.com/mr-harishv/carbon-labs/tree/main/packages/primitives"
click node_utilities "https://github.com/mr-harishv/carbon-labs/tree/main/packages/utilities"
click node_web_packages "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components"
click node_web_chat "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/chat"
click node_web_global_header "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/global-header"
click node_web_style_picker "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/style-picker"
click node_web_date_picker "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/v12/components/date-picker"
click node_web_generator "https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/tasks/generate"
click node_storybook_root "https://github.com/mr-harishv/carbon-labs/blob/main/.storybook"
click node_ci_release "https://github.com/mr-harishv/carbon-labs/blob/main/.github/workflows"
click node_examples_react "https://github.com/mr-harishv/carbon-labs/tree/main/examples/react"
click node_examples_web "https://github.com/mr-harishv/carbon-labs/tree/main/examples/web-components"

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_react_packages,node_react_uishell,node_react_theming,node_react_composites,node_react_mdx,node_react_plane3d toneBlue
class node_web_packages,node_web_chat,node_web_global_header,node_web_style_picker,node_web_date_picker toneAmber
class node_primitives,node_utilities toneMint
class node_react_generator,node_web_generator,node_storybook_root,node_ci_release toneRose
class node_examples_react,node_examples_web toneIndigo
class node_repo_root toneNeutral
```

## Components

### React packages

React-delivered UI components and composites.

- [React UI](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react): package family · One-package-per-component React delivery surface. · `packages/react`
- [UIShell](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/UIShell): react composite · Large shell system with header, side nav, popovers, profiles, and keyboard/accessibility helpers. · `packages/react/src/components/UIShell`
- [ThemeSettings](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/ThemeSettings): react system · Shared theme state and controls affecting global appearance. · `packages/react/src/components/ThemeSettings`
- [Other React comps](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components): react packages · Published component packages such as Calendar, Processing, Resizer, TagInput, TextHighlighter, WhatsNew, and more. · `packages/react/src/components`
- [MDX Components](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/MDXComponents): react docs ui · Reusable documentation/rendering components for Storybook and MDX content. · `packages/react/src/components/MDXComponents`
- [PlaneStack3D](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/src/components/PlaneStack3D): react visualization · Complex visualization package with layered subcomponents, layout, a11y, and theme context. · `packages/react/src/components/PlaneStack3D`

### Web components

Custom elements and their React bridge wrappers.

- [Web components](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components): package family · Custom elements with templates, SCSS, generated entrypoints, and optional React bridges. · `packages/web-components`
- [Chat](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/chat): web component suite · Multi-part chat system with elements plus service/adaptor layers. · `packages/web-components/src/components/chat`
- [GlobalHeader](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/global-header): web composite · Large header system with contexts, auth, scripts, side nav, and React wrapper boundary. · `packages/web-components/src/components/global-header`
- [StylePicker](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/components/style-picker): web composite · Theme and style selection system with grouped options, context, and rendering utilities. · `packages/web-components/src/components/style-picker`
- [DatePicker](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/src/v12/components/date-picker): web bridge · Web-component date picker built around adapters and reusable internal component logic. · `packages/web-components/src/v12/components/date-picker`

### Shared layers

Headless logic and cross-package helpers.

- [Primitives](https://github.com/mr-harishv/carbon-labs/tree/main/packages/primitives): headless package · Shared state machines and non-visual behavior, especially date-picker logic. · `packages/primitives`
- [Utilities](https://github.com/mr-harishv/carbon-labs/tree/main/packages/utilities): shared helpers · Cross-package helper functions and generic runtime helpers. · `packages/utilities`

### Tooling

Scaffolding, build tasks, Storybook, CI, and release automation.

- [React generator](https://github.com/mr-harishv/carbon-labs/tree/main/packages/react/tasks/generate): scaffold task · Task pipeline and templates for creating new React component packages. · `packages/react/tasks/generate`
- [Web generator](https://github.com/mr-harishv/carbon-labs/tree/main/packages/web-components/tasks/generate): scaffold task · Task pipeline and templates for creating new web-component packages. · `packages/web-components/tasks/generate`
- [Storybook](https://github.com/mr-harishv/carbon-labs/blob/main/.storybook): docs runtime · Root and package-level Storybook configuration, stories, docs, and welcome surfaces. · `.storybook`
- [CI & release](https://github.com/mr-harishv/carbon-labs/blob/main/.github/workflows): automation · GitHub Actions, publish workflows, Netlify config, and release automation. · `.github/workflows`

### Examples

Integration/demo surfaces for the supported consumption models.

- [React examples](https://github.com/mr-harishv/carbon-labs/tree/main/examples/react): vite demos · Integration demos validating React consumption in realistic app contexts. · `examples/react`
- [Web examples](https://github.com/mr-harishv/carbon-labs/tree/main/examples/web-components): vite demos · Integration demos for browser-native custom elements and CDN usage. · `examples/web-components`

### Other components

- **Carbon Labs**: monorepo · Independently published UI packages organized by runtime and delivery model.

## Connections

- Carbon Labs → React UI: contains · Monorepo delivers React package family.
- Carbon Labs → Web components: contains · Monorepo delivers web-component family.
- Carbon Labs → Primitives: contains · Shared headless behavior lives here.
- Carbon Labs → Utilities: contains · Cross-package helpers live here.
- Carbon Labs → Storybook: docs layer · Repository-wide Storybook setup and welcome content.
- Carbon Labs → CI & release: automation · CI, release, and publish workflows.
- Carbon Labs → React examples: contains · React integration demos.
- Carbon Labs → Web examples: contains · Web-component integration demos.
- React UI → UIShell: includes · Major composite React subsystem.
- React UI → ThemeSettings: includes · Theme state and controls subsystem.
- React UI → PlaneStack3D: includes · Complex visualization package.
- React UI → MDX Components: includes · Documentation rendering components.
- React UI → Other React comps: includes · Other published React components.
- React generator → React UI: scaffolds · Creates standardized React component packages.
- Web components → Chat: includes · Large multi-element chat suite.
- Web components → GlobalHeader: includes · Large header and auth/context subsystem.
- Web components → StylePicker: includes · Theme/style selection subsystem.
- Web components → DatePicker: includes · V12 date-picker bridge and implementation.
- Web generator → Web components: scaffolds · Creates standardized web-component packages.
- PlaneStack3D → Primitives: reuses · Shares headless behavior and utilities where needed.
- UIShell → Utilities: reuses · Uses common helpers such as prefixing and settings utilities.
- ThemeSettings → Utilities: reuses · Shares settings/prefix helpers.
- GlobalHeader → Utilities: reuses · Uses shared runtime helpers where applicable.
- DatePicker → Primitives: adapts · Builds on headless date-picker behavior.
- StylePicker → ThemeSettings: mirrors · Corresponding theme control boundary across runtimes.
- Storybook → React UI: documents · Stories and MDX for React packages.
- Storybook → Web components: documents · Stories and MDX for web-component packages.
- CI & release → Storybook: publishes · Storybook is deployed separately from package artifacts.
- CI & release → React UI: releases · Package builds and publishes React artifacts.
- CI & release → Web components: releases · Package builds and publishes web-component artifacts.
- React examples → React UI: consumes · Validates React packages in app contexts.
- Web examples → Web components: consumes · Validates custom elements in browser contexts.