# alphagov/govuk-design-system architecture

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

## Overview

##### Project type and purpose
This is a static-site generator for the GOV.UK Design System website. It consumes Markdown and Nunjucks templates (in src/), applies a pipeline of Metalsmith plugins and other Node.js modules (in lib/), bundles CSS (Sass) and JavaScript (Rollup), and outputs a fully static site (in build/). It includes a local dev server (Browsersync), automated tests (Jest + Puppeteer), linting (ESLint, Stylelint, HTMLValidate), and CI/CD (GitHub Actions → Netlify).

##### File structure
- Top-level build orchestrators in tasks/ (build.js, serve.js, start.js) invoke the pipeline.
- lib/ holds custom processing modules and Metalsmith plugins (render-markdown, lunr-index, fingerprinting, highlight, nunjucks integration, sitemap generation).
- src/ contains the content:
– Nunjucks pages & layouts (src/**/*.njk, views/)
– Markdown (src/**/*.md)
– Static assets: images/, styles (Sass under stylesheets/, plus govuk-frontend via NPM), and JavaScript components (src/javascripts/, bundled via Rollup).
- config/ and rollup.config.js define ports, paths, plugin options.
- __tests__ and lib/**/__tests__ contain unit and integration tests.
- .github/workflows drives CI.

##### Key README insights
- Node.js + NPM scripts for dev (npm start), build (npm run build), lint (npm run lint).
- CI runs tests, lints, builds on each push, and deploys via Netlify as per netlify.toml.
- Dependencies include govuk-frontend, Metalsmith ecosystem, Nunjucks, Rollup, Browsersync.

##### Diagramming the architecture
a. Main components:
– Developer environment (local Git repo, Node.js + NPM, nvm)
– Build orchestrator (tasks/start.js → tasks/build.js → tasks/serve.js)
– Processing pipeline:
- Read content (src/*.md + src/**/*.njk)
- Metalsmith core with plugins: render-markdown, metalsmith-lunr-index, fingerprint assets, generate-sitemap
- Nunjucks renderer (views/layouts + views/partials)
- Sass compiler (stylesheets → CSS via PostCSS/autoprefixer)
- Rollup bundler (src/javascripts → bundle.js)
– Output folder (build/) containing static HTML, CSS, JS, images, sitemap.xml
– Dev server (Browsersync) or production host (Netlify/CND)
– External services: GitHub (repo + Actions), NPM registry (govuk-frontend), Netlify

b. Relationships & data flows:
- Developer commits → GitHub → GitHub Actions
- CI: checkout → npm install → run lint/tests → run build → on success, Netlify deploy
- Locally, npm start runs build pipeline, watches files, serves via Browsersync
- End users request HTML/CSS/JS from Netlify CDN

c. Architectural patterns & principles:
- Plugin pipeline (Metalsmith) for content transformations
- Separation of concerns: content (src/), view templates (views/), processing logic (lib/), configuration (config/), orchestration (tasks/)
- Modular bundling: Rollup for JS, Sass modules for styles, Nunjucks for templates
- CI/CD automation with GitHub Actions & Netlify

d. Key technologies/frameworks:
- Node.js, NPM
- Metalsmith + custom plugins (in lib/)
- Nunjucks templating (views/)
- Sass + PostCSS/autoprefixer (stylesheets/)
- Rollup (rollup.config.js) bundling JS components
- Browsersync (config/browsersync.js)
- Jest + Puppeteer for testing
- GitHub Actions for CI
- Netlify (netlify.toml) for deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Developer and Version Control
  subgraph "Developer Environment"
    Dev["Local Git Repo & Node.js/NPM"]:::external
  end
  Dev -->|"commit & push"| GitHub["GitHub"]:::external
  click Dev "https://github.com/alphagov/govuk-design-system/tree/main/nvm"
  click Dev "https://github.com/alphagov/govuk-design-system/blob/main/package.json"

  %% CI/CD Pipeline
  subgraph "CI/CD"
    GitHub -->|"trigger CI"| Actions["GitHub Actions"]:::external
    Actions -->|"run lint & tests"| CI_LintTests["Lint & Tests"]:::processing
    CI_LintTests -->|"npm run build"| TasksStart
    Actions -->|"deploy build"| Netlify["Netlify CDN"]:::external
    Netlify -->|"serve static site"| Users["End Users"]:::external
  end

  %% Build Orchestrator
  subgraph "Build Orchestrator"
    TasksStart["tasks/start.js"]:::processing
    TasksBuild["tasks/build.js"]:::processing
    TasksServe["tasks/serve.js"]:::processing
    TasksStart --> TasksBuild --> TasksServe
  end
  click TasksStart "https://github.com/alphagov/govuk-design-system/blob/main/tasks/start.js"
  click TasksBuild "https://github.com/alphagov/govuk-design-system/blob/main/tasks/build.js"
  click TasksServe "https://github.com/alphagov/govuk-design-system/blob/main/tasks/serve.js"

  %% Processing Pipeline
  subgraph "Processing Pipeline"
    ContentReader["Content Reader\n(src/**/*.md, src/**/*.njk)"]:::source
    MetalsmithCore["Metalsmith Core & Pipeline Init\nlib/metalsmith.js"]:::processing
    ContentReader --> MetalsmithCore

    subgraph "Metalsmith Plugins" 
      Markdown["Render Markdown\nlib/metalsmith-render-markdown/index.js"]:::processing
      LunrIndex["Lunr Search Index\nlib/metalsmith-lunr-index/index.js"]:::processing
      Fingerprint["Asset Fingerprinting\nlib/fingerprints/index.js"]:::processing
      Sitemap["Sitemap Generation\nlib/generate-sitemap.js"]:::processing
      Markdown --> MetalsmithCore
      LunrIndex --> MetalsmithCore
      Fingerprint --> MetalsmithCore
      Sitemap --> MetalsmithCore
    end
    click Markdown "https://github.com/alphagov/govuk-design-system/blob/main/lib/metalsmith-render-markdown/index.js"
    click LunrIndex "https://github.com/alphagov/govuk-design-system/blob/main/lib/metalsmith-lunr-index/index.js"
    click Fingerprint "https://github.com/alphagov/govuk-design-system/blob/main/lib/fingerprints/index.js"
    click Sitemap "https://github.com/alphagov/govuk-design-system/blob/main/lib/generate-sitemap.js"

    NunjucksRenderer["Nunjucks Integration\nlib/nunjucks/index.js"]:::processing
    NunjucksFilters["Filters & Globals\nlib/nunjucks/filters.js\nlib/nunjucks/globals.js"]:::processing
    ContentTemplates["views/layouts & views/partials"]:::source
    MetalsmithCore --> NunjucksRenderer --> NunjucksFilters
    NunjucksFilters --> ContentTemplates
    click NunjucksRenderer "https://github.com/alphagov/govuk-design-system/blob/main/lib/nunjucks/index.js"
    click NunjucksFilters "https://github.com/alphagov/govuk-design-system/blob/main/lib/nunjucks/filters.js"
    click NunjucksFilters "https://github.com/alphagov/govuk-design-system/blob/main/lib/nunjucks/globals.js"
    click ContentTemplates "https://github.com/alphagov/govuk-design-system/tree/main/views/layouts"

    subgraph "Syntax Highlighting"
      Highlighter["Syntax Highlighter\nlib/highlighter.js"]:::processing
      HighlightNunjucks["Highlight Nunjucks\nlib/highlight-nunjucks/index.js"]:::processing
      Highlighter --> MetalsmithCore
      HighlightNunjucks --> MetalsmithCore
    end
    click Highlighter "https://github.com/alphagov/govuk-design-system/blob/main/lib/highlighter.js"
    click HighlightNunjucks "https://github.com/alphagov/govuk-design-system/blob/main/lib/highlight-nunjucks/index.js"

    subgraph "Custom Markdown Extensions"
      MarkedCore["Marked Core\nlib/marked/index.js"]:::processing
      MarkedExt["Extensions\nlib/marked/extension.js"]:::processing
      MarkedRenderer["Renderer\nlib/marked/renderer.js"]:::processing
      MarkedCore --> MetalsmithCore
      MarkedExt --> MetalsmithCore
      MarkedRenderer --> MetalsmithCore
    end
    click MarkedCore "https://github.com/alphagov/govuk-design-system/blob/main/lib/marked/index.js"
    click MarkedExt "https://github.com/alphagov/govuk-design-system/blob/main/lib/marked/extension.js"
    click MarkedRenderer "https://github.com/alphagov/govuk-design-system/blob/main/lib/marked/renderer.js"

    Navigation["Navigation Data Helper\nlib/navigation.js"]:::processing
    ConfigNav["config/navigation.js"]:::source
    Navigation --> MetalsmithCore
    click Navigation "https://github.com/alphagov/govuk-design-system/blob/main/lib/navigation.js"
    click ConfigNav "https://github.com/alphagov/govuk-design-system/blob/main/config/navigation.js"

    %% Asset Bundling
    SassCompiler["Sass Compiler\nsrc/stylesheets/**/*.scss"]:::processing
    RollupBundler["Rollup Bundler\nrollup.config.js & lib/rollup/index.js"]:::processing
    MetalsmithCore --> SassCompiler --> BuildOutput
    MetalsmithCore --> RollupBundler --> BuildOutput
    click SassCompiler "https://github.com/alphagov/govuk-design-system/blob/main/src/stylesheets/main.scss"
    click RollupBundler "https://github.com/alphagov/govuk-design-system/blob/main/rollup.config.js"
    click RollupBundler "https://github.com/alphagov/govuk-design-system/blob/main/lib/rollup/index.js"
  end

  %% Build Output
  subgraph "Build Output"
    BuildOutput["build/ (HTML, CSS, JS, images, sitemap.xml)"]:::output
  end

  %% Development Server
  TasksServe --> Browsersync["Browsersync Dev Server\nconfig/browsersync.js"]:::external
  Browsersync --> Users
  click Browsersync "https://github.com/alphagov/govuk-design-system/blob/main/config/browsersync.js"

  %% Tests and Lint
  subgraph "Testing & Linting"
    Tests["Jest & Puppeteer Tests\n__tests__ & lib/**/__tests__"]:::processing
    Lint["ESLint, Stylelint, HTMLValidate\n.eslintrc.js, stylelint.config.js, .htmlvalidate.js"]:::processing
    Tests --> CI_LintTests
    Lint --> CI_LintTests
    click Tests "https://github.com/alphagov/govuk-design-system/tree/main/__tests__"
    click Tests "https://github.com/alphagov/govuk-design-system/tree/main/lib/__tests__"
    click Lint "https://github.com/alphagov/govuk-design-system/blob/main/.eslintrc.js"
    click Lint "https://github.com/alphagov/govuk-design-system/blob/main/stylelint.config.js"
    click Lint "https://github.com/alphagov/govuk-design-system/blob/main/.htmlvalidate.js"
  end

  %% External Dependencies
  NPM["NPM Registry\ngovuk-frontend"]:::external
  NPM --> SassCompiler
  NPM --> RollupBundler

  %% CI/CD configs
  CIConfig["CI/CD Configs\n.github/workflows & netlify.toml"]:::external
  Actions --> CIConfig
  click CIConfig "https://github.com/alphagov/govuk-design-system/blob/main/.github/workflows/test.yaml"
  click CIConfig "https://github.com/alphagov/govuk-design-system/blob/main/.github/workflows/check-external-links.yaml"
  click CIConfig "https://github.com/alphagov/govuk-design-system/blob/main/.github/workflows/actions/install-and-build/action.yaml"
  click CIConfig "https://github.com/alphagov/govuk-design-system/blob/main/netlify.toml"

  classDef source fill:#e5ffe5,stroke:#333,stroke-width:1px
  classDef processing fill:#e5f0ff,stroke:#333,stroke-width:1px
  classDef output fill:#ffe5cc,stroke:#333,stroke-width:1px
  classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
```
