# carbon-design-system/carbon-website architecture

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

## Overview

##### Project Type & Purpose
- It’s a static site for the Carbon Design System documentation and demos.
- Built with GatsbyJS (a React-based SSG) and a custom theme (gatsby-theme-carbon).
- Publishes to a static hosting platform (e.g. Netlify/Vercel/CDN).

##### File Structure
- Root config: .babelrc, .eslintrc, gatsby-config.js, gatsby-node.js, gatsby-ssr.js, netlify.toml, nginx.conf.
- /src
– /components: React components (UI demos, charts, layout, etc.).
– /data: YAML/JSON source data for pages and GraphQL queries.
– /gatsby-theme-carbon: theme overrides & shared components.
– /pages: MDX/JSX page entrypoints.
– /styles: global & CSS modules.
– /plugins: custom Gatsby plugins for chart-index & component-index.
- CI/CD: .github/workflows (build, deploy, preview), netlify.toml, vercel.json.

##### Key Architecture Patterns
- “Data-as-Files”: src/data → Gatsby’s GraphQL layer → components/pages.
- Plugin-based extension: custom plugins under /plugins.
- Theme composition: custom theme in /gatsby-theme-carbon layered on top of Gatsby’s GraphQL & React.
- CI/CD-driven static build & deploy to CDN.

##### Main Components
a. Developer Workstation
– Git (GitHub repo)
– Node.js & Yarn
– Local Gatsby dev server (`yarn dev`)
b. Continuous Integration
– GitHub Actions workflows
– Netlify/Vercel build step (netlify.toml / vercel.json)
c. Gatsby Build Process
– Source files (components, pages, data, plugins, theme)
– GraphQL data layer (internal)
– Webpack bundler & SSG renderer
– Output: /public (static HTML, JS, CSS)
d. Hosting & Delivery
– Static web host (Netlify/Vercel/CDN)
– CDN edge nodes
– Client browser (React hydration & runtime navigation)

##### Relationships & Data Flows
- During Build: Source → GraphQL → HTML/JS/CSS → /public.
- At runtime: Browser requests static assets from CDN, hydrates React, loads data from inlined GraphQL JSON.

##### Technologies & Frameworks
- Build: Node.js, Yarn, GatsbyJS, Webpack, Babel
- Theming: gatsby-theme-carbon
- Data: MDX, YAML, JSON, GraphQL (internal)
- CI: GitHub Actions, Netlify/Vercel
- Hosting: Netlify/Vercel + CDN
- Dev tools: ESLint, Prettier, Husky pre-commit hooks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Workflow
    Dev["Developer Workstation\n(Node.js & Yarn)"]:::client
    GitHub["GitHub Repo"]:::code

    Dev -->|push code| GitHub

    %% Continuous Integration
    subgraph "Continuous Integration" 
        CI["GitHub Actions\n(.github/workflows)"]:::pipeline
        NetlifyBuild["Netlify/Vercel Build\n(netlify.toml/vercel.json)"]:::pipeline
    end

    GitHub -->|trigger CI| CI
    CI -->|runs build workflows| NetlifyBuild

    %% Gatsby Build Process
    subgraph "Gatsby Build Process" 
        Src["Source Files\n(src/components, src/pages, src/data,\nsrc/hooks, src/styles)"]:::code
        Theme["Theme Overrides\n(src/gatsby-theme-carbon)"]:::code
        Plugins["Custom Plugins\n(plugins/gatsby-plugin-chart-index,\nplugins/gatsby-plugin-component-index)"]:::code
        GraphQL["Gatsby GraphQL Layer"]:::pipeline
        Bundler["Webpack & SSG Renderer"]:::pipeline
        Public["/public Static Output"]:::hosting
    end

    NetlifyBuild -->|yarn build| Src
    Src --> GraphQL
    Theme --> GraphQL
    Plugins --> GraphQL
    GraphQL --> Bundler
    Bundler --> Public
    Public -->|deploy| Host["Netlify/Vercel Hosting"]:::hosting

    %% Hosting & Delivery
    Host --> CDN["CDN Edge Nodes"]:::hosting
    CDN -->|HTTP GET| Browser["Client Browser\n(React Hydration)"]:::client

    %% Click Events
    click .babelrc "https://github.com/carbon-design-system/carbon-website/blob/main/.babelrc"
    click .eslintrc "https://github.com/carbon-design-system/carbon-website/blob/main/.eslintrc"
    click gatsby-config.js "https://github.com/carbon-design-system/carbon-website/blob/main/gatsby-config.js"
    click gatsby-node.js "https://github.com/carbon-design-system/carbon-website/blob/main/gatsby-node.js"
    click gatsby-ssr.js "https://github.com/carbon-design-system/carbon-website/blob/main/gatsby-ssr.js"
    click netlify.toml "https://github.com/carbon-design-system/carbon-website/blob/main/netlify.toml"
    click vercel.json "https://github.com/carbon-design-system/carbon-website/blob/main/vercel.json"
    click nginx.conf "https://github.com/carbon-design-system/carbon-website/blob/main/nginx.conf"
    click CI "https://github.com/carbon-design-system/carbon-website/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/carbon-design-system/carbon-website/blob/main/.github/workflows/deploy-preview.yml"
    click CI "https://github.com/carbon-design-system/carbon-website/blob/main/.github/workflows/deploy.yml"
    click Theme "https://github.com/carbon-design-system/carbon-website/tree/main/src/gatsby-theme-carbon/"
    click Plugins "https://github.com/carbon-design-system/carbon-website/tree/main/plugins/gatsby-plugin-chart-index/"
    click Plugins "https://github.com/carbon-design-system/carbon-website/blob/main/plugins/gatsby-plugin-chart-index/gatsby-node.js"
    click Plugins "https://github.com/carbon-design-system/carbon-website/blob/main/plugins/gatsby-plugin-chart-index/src/schema.js"
    click Plugins "https://github.com/carbon-design-system/carbon-website/tree/main/plugins/gatsby-plugin-component-index/"
    click Plugins "https://github.com/carbon-design-system/carbon-website/blob/main/plugins/gatsby-plugin-component-index/gatsby-node.js"
    click Plugins "https://github.com/carbon-design-system/carbon-website/blob/main/plugins/gatsby-plugin-component-index/src/schema.js"
    click Src "https://github.com/carbon-design-system/carbon-website/tree/main/src/components/"
    click Src "https://github.com/carbon-design-system/carbon-website/tree/main/src/data/"
    click Src "https://github.com/carbon-design-system/carbon-website/tree/main/src/pages/"
    click Src "https://github.com/carbon-design-system/carbon-website/tree/main/src/styles/"
    click Src "https://github.com/carbon-design-system/carbon-website/tree/main/src/hooks/"
    click Static "https://github.com/carbon-design-system/carbon-website/tree/main/static/"
    click Static "https://github.com/carbon-design-system/carbon-website/tree/main/static/videos/"
    click Static "https://github.com/carbon-design-system/carbon-website/tree/main/static/files/"
    click Static "https://github.com/carbon-design-system/carbon-website/tree/main/static/status-icons/"
    click Public "https://github.com/carbon-design-system/carbon-website/tree/main//public"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef pipeline fill:#FFA500,stroke:#333,stroke-width:1px
    classDef hosting fill:#90EE90,stroke:#333,stroke-width:1px
    classDef client fill:#D8BFD8,stroke:#333,stroke-width:1px
```
