# carbon-design-system/carbon-components-vue architecture

> Architecture diagram of the GitHub repository carbon-design-system/carbon-components-vue, 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/carbon-design-system/carbon-components-vue
- Repository: https://github.com/carbon-design-system/carbon-components-vue

## Overview

##### Project type and purpose
- This is a full-stack open-source frontend library (monorepo) implementing Carbon Design System components in Vue 3.
- Provides dozens of reusable Vue single-file components, a Storybook for visual testing, a local Docker-based npm registry for publishing tests, and CI/CD via GitHub Actions.

##### Top-level structural analysis
- Monorepo managed by Lerna (`lerna.json`) and Yarn v3 (`.yarnrc.yml`, `.yarn/`).
- `src/` contains component packages (each under `components/` plus shared `global/`, `use/` directories).
- `storybook/` holds the standalone Storybook application.
- `local-dev/` runs a Docker-compose npm registry for test publishes.
- `.github/workflows/` defines CI, release, deploy Storybook, and stale-issue actions.

- Developer Workstation
- Git clone, local Yarn bootstrap & Lerna bootstrap
- Local build and test commands (Jest, Storybook serve)
- GitHub
- Source repository, PRs, issue management
- GitHub Actions: CI (lint/build/test), Storybook deploy, release publish
- Monorepo Packages
- Core Vue components under `src/components`
- Shared utilities under `src/global`, `src/use`
- Root package (`package.json`) & per-component entry points
- Build Tools & Scripts
- Yarn v3, Lerna CLI, Babel, TypeScript definitions
- Custom scripts (`postinstall.js`, `release.sh`)
- Jest for unit tests, Storybook for UI explorations
- Registries & Publishing
- Docker-Compose local registry (`local-dev/npm-registry`)
- npm public registry (via `yarn publish` or Lerna `publish`)
- Consumers
- External Vue 3 applications or Nuxt projects importing `@carbon/vue`

##### Relationships and workflows
- Data/Code flow: Developer → GitHub → CI → Build → Storybook & Tests → Registry
- Publishing flow: Build (packages) → Local-Dev registry → QA → Public npm registry
- Consumption flow: Consumer apps pull versions from npm registry → integrate with Vue app

##### Architectural patterns & principles
- Monorepo modularity (Lerna for multi-package repo)
- Single-File Component (SFC) pattern for Vue 3 composition API
- CI/CD pipelines for continuous integration and automated release
- Docker-based local registry for safe publish tests
- Storybook-driven development for visual component documentation

##### Key technologies & frameworks
- Vue 3, Composition API, Single File Components
- Yarn v3 Plug-and-Play, Lerna
- Jest & Vue Testing Library
- Storybook
- GitHub Actions
- Docker & Docker-Compose (npm registry)
- Babel, TypeScript declaration generation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        Dev["Developer<br/>Workstation"]:::dev
    end

    %% GitHub
    subgraph "GitHub"
        Repo["Repository @carbon/vue"]:::dev
        PR["PRs & Issues"]:::dev
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)"
        CI["Workflows"]:::ci
    end

    %% Monorepo Internals
    subgraph "Monorepo (src)"
        Lerna["lerna.json"]:::mon
        YarnCfg[".yarnrc.yml / .yarn/"]:::mon
        RootPkg["package.json"]:::mon
        Packages["Vue Components & Utilities<br/>(src/components/, src/global/, src/use/)"]:::mon
        StorybookCfg[".storybook/"]:::mon
    end

    %% Storybook App
    subgraph "Storybook Application"
        StorybookApp["storybook/"]:::mon
    end

    %% Local Dev Registry
    subgraph "Local Docker NPM Registry"
        LocalCompose["compose.yaml"]:::reg
        LocalStorage["npm-registry/storage"]:::reg
    end

    %% Build Tools & Scripts
    subgraph "Build Tools & Scripts"
        Babel["babel.config.js"]:::tools
        Jest["jest.config.js / setupAfterEnv.js / toBeAccessible.js"]:::tools
        Scripts["postinstall.js / .storybook/postinstall.js / devPreinstall.js / release.sh / addNamedComponentExports.js"]:::tools
    end

    %% Type Declarations & Entry
    subgraph "Type Declarations & Entry Points"
        Types["src/index.d.ts"]:::mon
        Entry["src/index.js"]:::mon
    end

    %% Consumers
    subgraph "Consumers"
        ConsumerApp["External Vue 3 Application"]:::dev
    end

    %% Flows
    Dev -->|"git clone & bootstrap"| Repo
    Repo -->|"push code"| CI
    CI -->|"lint, build, test"| Packages
    CI -->|"deploy Storybook"| StorybookApp
    CI -->|"release & publish"| LocalCompose
    LocalCompose --> LocalStorage
    LocalStorage -->|"QA publish"| CI
    CI -->|"publish to public npm"| Packages
    ConsumerApp -->|"install @carbon/vue"| Packages

    %% Click Events
    click Lerna "https://github.com/carbon-design-system/carbon-components-vue/blob/main/lerna.json"
    click YarnCfg "https://github.com/carbon-design-system/carbon-components-vue/blob/main/.yarnrc.yml"
    click YarnCfg "https://github.com/carbon-design-system/carbon-components-vue/tree/main/.yarn/"
    click RootPkg "https://github.com/carbon-design-system/carbon-components-vue/blob/main/package.json"
    click Packages "https://github.com/carbon-design-system/carbon-components-vue/tree/main/src/components/"
    click Packages "https://github.com/carbon-design-system/carbon-components-vue/tree/main/src/global/"
    click Packages "https://github.com/carbon-design-system/carbon-components-vue/tree/main/src/use/"
    click StorybookCfg "https://github.com/carbon-design-system/carbon-components-vue/tree/main/.storybook/"
    click StorybookApp "https://github.com/carbon-design-system/carbon-components-vue/tree/main/storybook/"
    click LocalCompose "https://github.com/carbon-design-system/carbon-components-vue/blob/main/local-dev/compose.yaml"
    click LocalStorage "https://github.com/carbon-design-system/carbon-components-vue/tree/main/local-dev/npm-registry/storage"
    click Babel "https://github.com/carbon-design-system/carbon-components-vue/blob/main/babel.config.js"
    click Jest "https://github.com/carbon-design-system/carbon-components-vue/blob/main/jest.config.js"
    click Scripts "https://github.com/carbon-design-system/carbon-components-vue/blob/main/postinstall.js"
    click Scripts "https://github.com/carbon-design-system/carbon-components-vue/blob/main/.storybook/postinstall.js"
    click Scripts "https://github.com/carbon-design-system/carbon-components-vue/blob/main/devPreinstall.js"
    click Scripts "https://github.com/carbon-design-system/carbon-components-vue/blob/main/release.sh"
    click Scripts "https://github.com/carbon-design-system/carbon-components-vue/blob/main/addNamedComponentExports.js"
    click Types "https://github.com/carbon-design-system/carbon-components-vue/blob/main/src/index.d.ts"
    click Entry "https://github.com/carbon-design-system/carbon-components-vue/blob/main/src/index.js"

    %% Styles
    classDef dev fill:#D0E6FF,stroke:#000,color:#000
    classDef ci fill:#FFD8A8,stroke:#000,color:#000
    classDef mon fill:#E0E0E0,stroke:#000,color:#000
    classDef reg fill:#C8E6C9,stroke:#000,color:#000
    classDef tools fill:#F0F0F0,stroke:#000,color:#000
```
