# skyscanner/backpack architecture

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

- Interactive diagram: https://gitdiagram.com/skyscanner/backpack
- Repository: https://github.com/skyscanner/backpack

## Overview

##### Project type and purpose
- This is a front-end design system monorepo (“Backpack”) containing dozens of React component packages, SCSS mixins, theming utilities, storybook configuration, examples and build scripts. Its purpose is to provide a consistent library of UI building blocks, styles and tooling for Skyscanner’s products.

##### File structure
- Top-level config and tooling directories:
- .github/ (CI/CD workflows, templates)
- .storybook/ (Storybook config)
- scripts/ (shell and JS helpers for linting, testing, transpilation)
- gulpfile.js (per-component build tasks)
- babel.config.js, tsconfig.json, webpack/postCssPlugins.js
- examples/ (per-component playground code, stories)
- packages/
- A folder per component (bpk-component-xyz), each with its own src/, tests, snapshots, README, index.(js|ts)
- Higher-level packages: bpk-mixins, bpk-stylesheets, bpk-theming, bpk-react-utils
- Root manifests: package.json, package-lock.json, .gitmodules
- Linting/formatting: .eslintrc, .stylelintrc, .prettierrc, Husky pre-commit hooks, Percy visual-testing config

##### README for additional insights
- Confirms a monorepo distribution (@skyscanner/backpack-web), a long list of internal packages, external dependencies (@skyscanner/bpk-svgs, bpk-foundations-web).
- Points to documentation site and changelog, suggests CI automation via GitHub Actions.

a. Main components
- Developer Workstation (IDE, Git, npm/yarn CLI)
- Version Control Platform (GitHub repo with submodules)
- Monorepo root – code organization:
- Config & tooling (babel, webpack, gulp, lint, test scripts)
- packages/ (individual React component libraries)
- examples/ & storybook/ (documentation playground)
- Build & Test Pipeline (GitHub Actions + Percy visual tests, Jest + snapshot tests, lint, typecheck)
- Artifact registry (npmjs.com for publishing individual @skyscanner/backpack-web packages)
- Documentation site (consumes storybook build or static site generator)
- External Foundations (bpk-svgs, bpk-foundations-web packages from separate repo)

b. Relationships & data flows
- Developer → GitHub (push PR)
- GitHub Actions → run lint, tests, storybook build, Percy checks
- On successful CI → npm publish individual packages
- Consumers (other Skyscanner apps) → npm install @skyscanner/backpack-web packages
- Developer/Designer → run Storybook locally or view hosted docs
- Build scripts (gulp, webpack, babel) transform src/ → dist/ bundles

c. Architectural patterns & design principles
- Monorepo with package-per-component promotes code reuse and version consistency
- Workspace isolation: each package has its own entry point, tests and styling
- Automated CI gating ensures quality (lint, typecheck, accessibility tests)
- Storybook as living documentation and visual QA
- Separation of concerns: theming, raw mixins, React utils are distinct foundational layers

d. Key technologies & frameworks
- Node.js, npm/Yarn (monorepo package management)
- React + TypeScript/JavaScript
- SCSS modules and theming via bpk-theming
- Babel, Webpack, Gulp for transpilation & bundling
- Jest + snapshot tests, accessibility tests
- ESLint, Stylelint, Prettier for code quality
- Husky hooks, Danger.js, Dependabot for maintenance
- Storybook for component sandboxing
- GitHub Actions + Percy for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Dev["Developer"]:::developer
    Des["Designer"]:::developer
    Dev -->|push code / PR| GitHub["GitHub Repo"]:::vcs
    Des -->|view docs| DocsSite["Documentation Site"]:::docs

    %% Version Control & CI/CD Configuration
    subgraph "Version Control & CI/CD" 
        GitHub
        Workflows[".github/workflows"]:::config
        GitHub --> Workflows
    end
    click Workflows "https://github.com/skyscanner/backpack/tree/main/.github/workflows"

    %% Monorepo Structure
    subgraph "Monorepo (Backpack)" 
        subgraph "Config & Tooling"
            ESLint[".eslintrc"]:::config
            Stylelint[".stylelintrc.json"]:::config
            Prettier[".prettierrc"]:::config
            Husky[".husky/pre-commit"]:::config
            ESLint -->|quality| Husky
            Stylelint -->|style| Husky
            Prettier -->|format| Husky
            click ESLint "https://github.com/skyscanner/backpack/blob/main/.eslintrc"
            click Stylelint "https://github.com/skyscanner/backpack/blob/main/.stylelintrc.json"
            click Prettier "https://github.com/skyscanner/backpack/blob/main/.prettierrc"
            click Husky "https://github.com/skyscanner/backpack/tree/main/.husky/pre-commit"
        end

        subgraph "Build & Transpile Config"
            Babel["babel.config.js"]:::config
            TS["tsconfig.json"]:::config
            PostCSS["scripts/webpack/postCssPlugins.js"]:::scripts
            Gulp["gulpfile.js"]:::config
            click Babel "https://github.com/skyscanner/backpack/blob/main/babel.config.js"
            click TS "https://github.com/skyscanner/backpack/blob/main/tsconfig.json"
            click PostCSS "https://github.com/skyscanner/backpack/blob/main/scripts/webpack/postCssPlugins.js"
            click Gulp "https://github.com/skyscanner/backpack/blob/main/gulpfile.js"
        end

        subgraph "Storybook"
            SBMain[".storybook/main.ts"]:::config
            SBPreview[".storybook/preview.tsx"]:::config
            SBBabel[".storybook/babel.config.js"]:::config
            SBWebpack[".storybook/webpack.config.js"]:::config
            click SBMain "https://github.com/skyscanner/backpack/blob/main/.storybook/main.ts"
            click SBPreview "https://github.com/skyscanner/backpack/blob/main/.storybook/preview.tsx"
            click SBBabel "https://github.com/skyscanner/backpack/blob/main/.storybook/babel.config.js"
            click SBWebpack "https://github.com/skyscanner/backpack/blob/main/.storybook/webpack.config.js"
        end

        subgraph "Scripts & Examples"
            Scripts["scripts/"]:::scripts
            Examples["examples/"]:::scripts
            click Scripts "https://github.com/skyscanner/backpack/tree/main/scripts/"
            click Examples "https://github.com/skyscanner/backpack/tree/main/examples/"
        end

        subgraph "Root Manifests"
            PKG["package.json"]:::config
            PKGLock["package-lock.json"]:::config
            GitSub[".gitmodules"]:::config
            click PKG "https://github.com/skyscanner/backpack/blob/main/package.json"
            click PKGLock "https://github.com/skyscanner/backpack/blob/main/package-lock.json"
            click GitSub "https://github.com/skyscanner/backpack/blob/main/.gitmodules"
        end

        subgraph "Packages"
            subgraph "Foundational"
                Mixins["bpk-mixins"]:::packages
                Stylesheets["bpk-stylesheets"]:::packages
                Theming["bpk-theming"]:::packages
                ReactUtils["bpk-react-utils"]:::packages
                Scrim["bpk-scrim-utils"]:::packages
                click Mixins "https://github.com/skyscanner/backpack/tree/main/packages/bpk-mixins"
                click Stylesheets "https://github.com/skyscanner/backpack/tree/main/packages/bpk-stylesheets"
                click Theming "https://github.com/skyscanner/backpack/tree/main/packages/bpk-theming"
                click ReactUtils "https://github.com/skyscanner/backpack/tree/main/packages/bpk-react-utils"
                click Scrim "https://github.com/skyscanner/backpack/tree/main/packages/bpk-scrim-utils"
            end
            subgraph "Components"
                Accordion["bpk-component-accordion"]:::packages
                Button["bpk-component-button"]:::packages
                Card["bpk-component-card"]:::packages
                Others["..."]:::packages
                click Accordion "https://github.com/skyscanner/backpack/tree/main/packages/bpk-component-accordion"
                click Button "https://github.com/skyscanner/backpack/tree/main/packages/bpk-component-button"
                click Card "https://github.com/skyscanner/backpack/tree/main/packages/bpk-component-card"
            end
        end
    end

    %% CI/CD Pipeline
    GitHub -->|trigger CI| CI["GitHub Actions"]:::ci
    CI --> Lint["ESLint/Stylelint"]:::ci
    CI --> Test["Jest + Snapshots"]:::ci
    CI --> Percy["Percy Visual Tests"]:::ci
    CI --> Build["Storybook Build"]:::ci
    Build --> DocsSite
    CI --> Publish["npm Publish"]:::registry

    %% Artifact Registry and Consumers
    Publish --> NPM["npm Registry (@skyscanner/backpack-web)"]:::registry
    NPM -->|install| ConsumerApps["Skyscanner Apps"]:::consumer
    DocsSite -->|hosts| ConsumerDocs["Hosted Storybook Docs"]:::docs

    %% Styles
    classDef developer fill:#E3F2FD,stroke:#1976D2,color:#0D47A1;
    classDef vcs fill:#FFF3E0,stroke:#E65100,color:#BF360C;
    classDef config fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef scripts fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef packages fill:#E1F5FE,stroke:#0277BD,color:#01579B;
    classDef ci fill:#FFEBEE,stroke:#C62828,color:#B71C1C;
    classDef registry fill:#FFFDE7,stroke:#F9A825,color:#F57F17;
    classDef consumer fill:#ECEFF1,stroke:#607D8B,color:#263238;
    classDef docs fill:#FFF8E1,stroke:#FF8F00,color:#E65100;
```
