mr-harishv/carbon-labs

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.