# codecademy/gamut architecture

> Architecture diagram of the GitHub repository codecademy/gamut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codecademy/gamut
- Repository: https://github.com/codecademy/gamut

## Overview

##### Project type and purpose
- This is a monorepo for a React component library & design system (“Gamut”) plus its documentation sandbox (Storybook styleguide).
- It also includes CI/CD pipelines (CircleCI / GitHub Actions) that build, test, and publish packages and deploy the styleguide.

##### Main components
A. Monorepo Root
- yarn workspace & Lerna config (package.json, lerna.json, nx.json)
- Top-level scripts: build, test, nx commands
B. Package Groups (packages/*)
1. Core UI packages
– @codecademy/gamut (React components)
– @codecademy/gamut-styles (styling utilities & SCSS assets)
2. Utility libraries
– @codecademy/variance (TypeScript CSS-in-JS helpers)
– @codecademy/gamut-tests (testing helpers)
– @codecademy/macros (Babel macros)
3. styleguide
– Storybook server & MDX docs (packages/styleguide)
4. scripts & tooling
– jest presets & transformers (script/jest)
– Babel configs at root and per-package
C. CI/CD Pipelines
- GitHub Actions & CircleCI workflows (in .github/ and .circleci/)
- Steps: lint → test → build → publish α / publish release → deploy styleguide
D. External Services
- GitHub (source & PR triggers)
- npm Registry (package publish & consume)
- Static hosting (Netlify or GitHub Pages for storybook)
- Slack / bots (PR comments from alpha deploys)

##### Relationships and data flows
- Developer → Git push/PR → GitHub triggers → CI jobs
- CI: installs dependencies (Yarn), bootstraps with Lerna, runs Nx task graph
- Each package: build → run tests → output to /dist
- On merge to main: automatic publish to npm (via CircleCI), automatic styleguide build & deploy
- Downstream application: installs @codecademy/gamut-kit (or individual packages) from npm; IDE intellisense via peerDependencies

##### Architectural patterns and principles
- Monorepo with coarse-grained package separation (single purpose per package)
- Lerna & Yarn workspaces for dependency linking and versioning
- Nx for caching, task orchestration, and incremental rebuilds
- Conventional commits & CI gating for automated changelog & semantic versioning
- Storybook MDX documentation co-located with code

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actors
    Dev["Developer"]:::actor
    App["Downstream Application"]:::actor
    GitHub["GitHub"]:::external
    NPM["npm Registry"]:::external
    Hosting["Static Hosting"]:::external
    Browser["Browser / User"]:::actor

    %% Monorepo container
    subgraph "Monorepo Root" 
        direction TB
        Config["Lerna & Yarn Workspaces"]:::code
        click Config "https://github.com/codecademy/gamut/blob/main//package.json"
        click Config "https://github.com/codecademy/gamut/blob/main//lerna.json"
        click Config "https://github.com/codecademy/gamut/blob/main//nx.json"

        subgraph "Scripts & Tooling"
            direction TB
            Jest["jest presets & transformers"]:::tooling
            click Jest "https://github.com/codecademy/gamut/tree/main//script/jest"
            BabelRoot["Root Babel Configs"]:::tooling
            click BabelRoot "https://github.com/codecademy/gamut/blob/main//babel.config.js"
            click BabelRoot "https://github.com/codecademy/gamut/blob/main//babel.defaults.js"
        end

        subgraph "Packages/*"
            direction TB
            subgraph "Core UI Packages"
                direction TB
                Gamut["@codecademy/gamut"]:::code
                click Gamut "https://github.com/codecademy/gamut/tree/main//packages/gamut"
                Styles["@codecademy/gamut-styles"]:::code
                click Styles "https://github.com/codecademy/gamut/tree/main//packages/gamut-styles"
                Icons["@codecademy/gamut-icons"]:::code
                click Icons "https://github.com/codecademy/gamut/tree/main//packages/gamut-icons"
                Illus["@codecademy/gamut-illustrations"]:::code
                click Illus "https://github.com/codecademy/gamut/tree/main//packages/gamut-illustrations"
                Patterns["@codecademy/gamut-patterns"]:::code
                click Patterns "https://github.com/codecademy/gamut/tree/main//packages/gamut-patterns"
            end
            subgraph "Utility Libraries"
                direction TB
                Variance["@codecademy/variance"]:::code
                click Variance "https://github.com/codecademy/gamut/tree/main//packages/variance"
                GamutTests["@codecademy/gamut-tests"]:::code
                click GamutTests "https://github.com/codecademy/gamut/tree/main//packages/gamut-tests"
                Macros["@codecademy/macros"]:::code
                click Macros "https://github.com/codecademy/gamut/tree/main//packages/macros"
            end
            subgraph "Styleguide"
                Styleguide["packages/styleguide"]:::code
                click Styleguide "https://github.com/codecademy/gamut/tree/main//packages/styleguide"
            end
        end

        subgraph "CI/CD Pipelines"
            direction TB
            CI["CI/CD Workflows"]:::tooling
            click CI "https://github.com/codecademy/gamut/blob/main//.circleci/config.yml"
            click CI "https://github.com/codecademy/gamut/blob/main//.github/workflows/*.yml"
            Nx["Nx Task Orchestration"]:::tooling
        end
    end

    %% Flows
    Dev -->|push/PR| GitHub
    GitHub -->|trigger| CI
    CI -->|bootstrap & install| Config
    CI -->|run tasks| Nx
    Nx -->|build & test| Gamut
    Nx -->|build & test| Styles
    Nx -->|build & test| Icons
    Nx -->|build & test| Illus
    Nx -->|build & test| Patterns
    Nx -->|build & test| Variance
    Nx -->|build & test| GamutTests
    Nx -->|build & test| Macros
    Nx -->|build & test| Styleguide

    CI -->|publish| NPM
    CI -->|deploy styleguide| Hosting
    Hosting -->|serves docs| Browser

    App -->|install packages| NPM

    %% Styling
    classDef code fill:#E3F2FD,stroke:#90CAF9;
    classDef tooling fill:#C8E6C9,stroke:#66BB6A;
    classDef external fill:#FFE0B2,stroke:#FF8A65;
    classDef actor fill:#F5F5F5,stroke:#BDBDBD;
```
