# instructure/instructure-ui architecture

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

- Interactive diagram: https://gitdiagram.com/instructure/instructure-ui
- Repository: https://github.com/instructure/instructure-ui

## Overview

##### Project Type and Purpose
- This is an open-source, React-based UI framework & design system (“Instructure UI”) delivered as a monorepo.
- It houses hundreds of small, focused packages (components, utilities, themes, testing tools, scripts) managed via Lerna and published to NPM.
- It also contains documentation, examples, and end-to-end/regression test runners (Cypress, Karma, Vitest).

##### High-Level Architecture
- Monorepo Root
– Configuration: ESLint, Prettier, TypeScript (tsconfig.*.json), Babel, Husky (git hooks), commitlint.
– Orchestration: Lerna (lerna.json), custom build/test/deploy scripts (in /scripts and /.github/workflows).
- Package Groups (under /packages)
– UI Components (e.g., ui-buttons, ui-dialog, ui-menu, …)
– Theming & Styles (canvas-theme, canvas-high-contrast-theme, ui-themes, shared-types)
– Utilities (ui-utils, ui-dom-utils, ui-test-utils, ui-scripts, pkg-utils, command-utils, debounce, uid, etc.)
– Plugins/Config (babel-plugin-transform-imports, ui-babel-preset, ui-webpack-config, ui-karma-config)
– Docs & Examples ( __docs__, __examples__, docs/, packages/__docs__, packages/__examples__ )
– Regression & E2E tests ( regen-test, cypress, Karma config, Vitest config )
- CI/CD Pipelines
– GitHub Actions: lint, type-check, unit/regression tests, visual regression, versioning, publish to NPM, deploy docs.
– Manual workflows for releasing (to NPM or site previews).
- External Services
– npm registry (package publish)
– Website host (instructure.design docs site)
– GitHub (source, Issues, PRs, CodeQL)

##### Relationships & Data Flows
- Developer → GitHub Push/PR
– Husky → lint-staged → Pre-commit tests
– commitlint on commit messages
- GitHub Actions triggered on push/PR
– Steps: install dependencies → type-check → unit tests (Vitest/Karma) → Cypress E2E → visual regression → build packages → version bump (calculateVersion.sh) → publish
- Build Outputs
– Component bundles → NPM packages
– Documentation site static assets → Deployed website
- Consumers
– App developers import published packages from NPM
– Documentation site visitors view examples & API docs
– CI regression-test runner ensures backwards-compatibility

##### Architectural Patterns & Principles
- Monorepo modularization: each package is a small, single-responsibility module.
- “Build once, publish many”: shared build/config leveraged across packages (babel, TS, webpack).
- CI-driven quality gates: type safety, lint, unit/E2E, visual regression before merge/publish.
- Docs-as-code: examples and docs are first-class packages under the monorepo, built with custom scripts.
- Publish-on-tag: manual and automated release flows separate CI and publication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and source
    Dev["Developer"]:::external
    GH["GitHub"]:::external

    Dev -->|"push/PR"| GH

    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        Lerna["lerna.json"]:::tooling
        Babel["babel.config.js"]:::tooling
        TSRefs["tsconfig.references.json"]:::tooling
        ESLint["eslint.config.mjs"]:::tooling
        Prettier[".prettierrc.json"]:::tooling
        Commitlint["commitlint.config.js"]:::tooling
        Husky[".husky/"]:::tooling
        Scripts["/scripts/"]:::tooling
    end

    click Lerna "https://github.com/instructure/instructure-ui/blob/master//lerna.json"
    click Babel "https://github.com/instructure/instructure-ui/blob/master//babel.config.js"
    click TSRefs "https://github.com/instructure/instructure-ui/blob/master//tsconfig.references.json"
    click ESLint "https://github.com/instructure/instructure-ui/blob/master//eslint.config.mjs"
    click Prettier "https://github.com/instructure/instructure-ui/blob/master//.prettierrc.json"
    click Commitlint "https://github.com/instructure/instructure-ui/blob/master//commitlint.config.js"
    click Husky "https://github.com/instructure/instructure-ui/tree/master//.husky/"
    click Scripts "https://github.com/instructure/instructure-ui/blob/master//scripts/bootstrap.js"

    GH -->|"CI trigger"| CI

    %% CI/CD Pipelines
    subgraph "CI/CD Workflows"
        direction TB
        CodeQL["codeql-analysis.yml"]:::ci
        PRVal["pr-validation.yml"]:::ci
        Release["release.yml"]:::ci
        ManualRel["manual-release-to-npm.yml"]:::ci
        Deploy["deploy.yml"]:::ci
        VisualReg["visual-regression.yml"]:::ci
        Preview["preview.yml"]:::ci
        CalcVer["calculateVersion.sh"]:::ci
    end

    click CodeQL "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/codeql-analysis.yml"
    click PRVal "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/pr-validation.yml"
    click Release "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/release.yml"
    click ManualRel "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/manual-release-to-npm.yml"
    click Deploy "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/deploy.yml"
    click VisualReg "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/visual-regression.yml"
    click Preview "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/preview.yml"
    click CalcVer "https://github.com/instructure/instructure-ui/blob/master//.github/workflows/calculateVersion.sh"

    CI["GitHub Actions"]:::ci

    GH --> CI
    CI -->|"build packages"| Build
    CI -->|"run docs pipeline"| DocsBuild

    %% Build Outputs
    Build["Package Bundles"]:::frontend
    Build -->|"publish"| NPM

    %% Docs pipeline
    DocsBuild["Docs Build"]:::tooling
    DocsBuild -->|"deploy"| DocsHost

    %% Package Clusters
    subgraph "Packages"
        direction TB
        subgraph "UI Components" 
            direction TB
            UIButtons["ui-buttons"]:::frontend
            UIDialog["ui-dialog"]:::frontend
        end
        subgraph "Theming & Styles"
            direction TB
            CanvasTheme["canvas-theme"]:::frontend
            HighContrast["canvas-high-contrast-theme"]:::frontend
        end
        subgraph "Utilities"
            direction TB
            UIUtils["ui-utils"]:::tooling
        end
        subgraph "Build & Test Tooling"
            direction TB
            KArmaConf["ui-karma-config"]:::tooling
        end
        subgraph "Docs & Examples"
            direction TB
            GlobalDocs["/docs"]:::tooling
            MonoDocs["packages/__docs__"]:::tooling
        end
    end

    click UIButtons "https://github.com/instructure/instructure-ui/tree/master//packages/ui-buttons/"
    click CanvasTheme "https://github.com/instructure/instructure-ui/tree/master//packages/canvas-theme/"
    click UIUtils "https://github.com/instructure/instructure-ui/tree/master//packages/ui-utils/"
    click KArmaConf "https://github.com/instructure/instructure-ui/tree/master//packages/ui-karma-config/"
    click GlobalDocs "https://github.com/instructure/instructure-ui/tree/master//docs/"
    click MonoDocs "https://github.com/instructure/instructure-ui/tree/master//packages/__docs__/"

    %% External Services
    NPM["NPM Registry"]:::external
    DocsHost["Docs Host"]:::external

    %% Consumer Flow
    Consumer["App Developers"]:::external
    Consumer -->|"import packages"| NPM

    Visitor["Docs Visitors"]:::external
    Visitor -->|"view site"| DocsHost

    %% Dependencies
    SharedTypes["shared-types"]:::frontend
    SharedTypes -->|"dep on"| UIButtons

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef tooling fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef ci fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef external fill:#e0e0e0,stroke:#424242,color:#424242
```
