# nl-design-system/documentatie architecture

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

- Interactive diagram: https://gitdiagram.com/nl-design-system/documentatie
- Repository: https://github.com/nl-design-system/documentatie

## Overview

##### Project type and purpose
- This is a documentation website for the “NL Design System,” built as a static site using Docusaurus (React + Markdown/MDX).
- It’s a monorepo managed by pnpm, combining:
- Content (docs/, blog/, static/)
- Custom UI (src/components, src/theme)
- Two reusable packages (packages/archimate and packages/nlds-design-tokens)
- Build & test pipelines (.github/workflows, Docker/Apache for local simulation).

##### Architectural overview
- Content layer
- Markdown files under docs/ → pages on the site
- .mdx files for mixed Markdown+React
- blog/ for blog posts
- static/ for raw assets and redirects (.htaccess)
- Presentation layer
- src/components & src/theme override Docusaurus components
- CSS under src/css and component-specific .css files
- Design tokens consumed via @nl-design-system-tokens package
- Build system
- Docusaurus CLI invoked by pnpm scripts (build, start, serve)
- style-dictionary-driven token build (packages/nlds-design-tokens)
- TypeScript/JS bundling (babel.config.mjs, tsconfig.json)
- Local test environment
- Docker Compose + httpd.Dockerfile + httpd.conf for Apache testing of redirects
- CI/CD & QA
- GitHub Actions workflows: cd.yml (deploy), publish.yml (npm packages), require-autosquash.yml
- E2E tests with Playwright (test/e2e) and visual regression via Argos CI (test/visual)
- Hosting
- Production static hosting via Vercel or Apache on Docker (vercel.json present, compose.yaml)
- CDN for static assets, HTTPS, custom domain.

##### Main components
- “Authoring & Repo”
- Developers write Markdown/MDX, React components, token definitions
- GitHub repository with monorepo (pnpm-root)
- “CI/CD Pipeline”
- GitHub Actions build → lint → test → style-dictionary token build → Docusaurus build → deploy
- Argos CI for visual regression
- “Build System”
- Node.js, pnpm, Babel, Docusaurus CLI
- style-dictionary for design tokens
- TypeScript compile & bundling
- “Static Site Generator”
- Docusaurus Core & plugins (content-blog, content-docs, theme)
- Outputs HTML/CSS/JS and assets into build/
- “Hosting & Runtime”
- Static HTTP server (Vercel / Apache HTTPD + Docker)
- CDN & HTTPS termination
- .htaccess redirects tested locally under Docker
- “Consumers”
- End users (browsers) request pages
- Designers/Developers consume tokens from npm package

##### Relationships & interactions
- Author push → GitHub
→ triggers CI/CD
→ installs dependencies (pnpm install)
→ runs lint, tests, token build
→ runs Docusaurus build
→ publishes build artifacts
→ deploys to hosting
- Local dev
→ pnpm run start → Docusaurus server with hot-reload
→ (optional) Docker Compose brings up Apache to serve build/
- End user requests
→ static files served from CDN/HTTP server
→ JS hydration for dynamic components (contrast checker, MDX React components).

##### Architectural patterns & principles
- Monorepo with package isolation (pnpm-workspace.yaml)
- Static site generation (SSG) for performance and security
- Composition: Markdown + MDX + React components
- Theming & extensibility via Docusaurus theme overrides
- CI as code: GitHub Actions define build, test, publish, deploy
- Token-driven styling: central design tokens packaged for reuse

##### Technologies & frameworks
- Docusaurus (React, MDX, content-docs, content-blog)
- Node.js, pnpm, Babel, TypeScript
- style-dictionary (design tokens)
- GitHub Actions, Playwright, Argos CI
- Docker Compose, Apache HTTPD
- Vercel (optional), static CDN

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Interaction
    Dev["Developer"]:::external
    Dev -->|"push code / start dev"| Monorepo

    %% Monorepo Repository
    subgraph "Monorepo Repository" 
        direction TB
        Repo[/"GitHub Monorepo"/]:::parallelogram
        docs["docs/"]:::source
        blog["blog/"]:::source
        static["static/"]:::source
        htaccess["static/.htaccess"]:::source
        components["src/components/"]:::source
        theme["src/theme/"]:::source
        css["src/css/custom.css"]:::source
        tokensPkg["packages/nlds-design-tokens/"]:::source
        sdConfig["style-dictionary-config.json"]:::source
        archPkg["packages/archimate/"]:::source
        pnpmWS["pnpm-workspace.yaml"]:::source
        lockfile["pnpm-lock.yaml"]:::source
        docusaurusCfg["docusaurus.config.ts"]:::source
        babelCfg["babel.config.mjs"]:::source
        tsCfg1["tsconfig.json"]:::source
        tsCfg2["tsconfig.commonjs.json"]:::source
        pkgJSON["package.json"]:::source
        navCfg["navConfig.ts"]:::source
        sideCfg["sidebarConfig.ts"]:::source
        footerCfg["footerConfig.ts"]:::source
        prismCfg["nldsPrism.ts"]:::source
        rehypeCfg["rehype-trailing-slash.ts"]:::source

        Repo --> docs
        Repo --> blog
        Repo --> static
        Repo --> htaccess
        Repo --> components
        Repo --> theme
        Repo --> css
        Repo --> tokensPkg
        tokensPkg --> sdConfig
        Repo --> archPkg
        Repo --> pnpmWS
        Repo --> lockfile
        Repo --> docusaurusCfg
        Repo --> babelCfg
        Repo --> tsCfg1
        Repo --> tsCfg2
        Repo --> pkgJSON
        Repo --> navCfg
        Repo --> sideCfg
        Repo --> footerCfg
        Repo --> prismCfg
        Repo --> rehypeCfg
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GHActions["GitHub Actions"]:::build
        lint["Lint & Pre-commit"]:::build
        tests["Unit & E2E Tests"]:::build
        tokenBuild["Style-dictionary Build"]:::build
        docusBuild["Docusaurus Build"]:::build
        argos["Argos CI (Visual)"]:::build
        publish["Publish Packages"]:::build
        deploy["Deploy Artifacts"]:::build

        Monorepo --> GHActions
        GHActions --> lint
        GHActions --> tests
        GHActions --> tokenBuild
        GHActions --> docusBuild
        GHActions --> argos
        GHActions --> publish
        GHActions --> deploy
    end

    %% Build System Components
    subgraph "Build System" 
        direction TB
        NodePNPM["Node.js & pnpm"]:::build
        Babel["Babel & TS Bundling"]:::build
        DocusaurusCLI["Docusaurus CLI"]:::build
        StyleDict["style-dictionary"]:::build

        docusBuild --> NodePNPM
        tokenBuild --> StyleDict
        NodePNPM --> Babel
        Babel --> DocusaurusCLI
    end

    %% Hosting & Runtime
    subgraph "Hosting & Runtime" 
        direction TB
        Vercel["Vercel CDN & HTTPS"]:::hosting
        Apache["Apache HTTPD (Docker)"]:::hosting
        Compose["Docker Compose"]:::hosting

        deploy --> Vercel
        deploy --> Apache
        Apache --> Compose
    end

    %% User Consumption
    subgraph "End Users & Consumers"
        direction TB
        Browser["Web Browser"]:::external
        Designers["Designers/Dev (Tokens)"]:::external

        Browser -->|"requests pages"| Vercel
        Browser -->|"requests pages"| Apache
        Designers -->|"npm install tokens"| tokensPkg
    end

    %% Local Development
    subgraph "Local Dev Environment"
        direction TB
        Dev -->|"pnpm run start"| LocalDocus
        LocalDocus["Docusaurus Dev Server"]:::build
        Dev --> Compose
        LocalDocus -->|hot-reload| components
        Compose --> Apache
    end

    %% Click Events
    click docs "https://github.com/nl-design-system/documentatie/tree/main/docs/"
    click blog "https://github.com/nl-design-system/documentatie/tree/main/blog/"
    click static "https://github.com/nl-design-system/documentatie/tree/main/static/"
    click htaccess "https://github.com/nl-design-system/documentatie/blob/main/static/.htaccess"
    click components "https://github.com/nl-design-system/documentatie/tree/main/src/components/"
    click theme "https://github.com/nl-design-system/documentatie/tree/main/src/theme/"
    click css "https://github.com/nl-design-system/documentatie/blob/main/src/css/custom.css"
    click tokensPkg "https://github.com/nl-design-system/documentatie/tree/main/packages/nlds-design-tokens/"
    click sdConfig "https://github.com/nl-design-system/documentatie/blob/main/packages/nlds-design-tokens/style-dictionary-config.json"
    click archPkg "https://github.com/nl-design-system/documentatie/tree/main/packages/archimate/"
    click pnpmWS "https://github.com/nl-design-system/documentatie/blob/main/pnpm-workspace.yaml"
    click lockfile "https://github.com/nl-design-system/documentatie/blob/main/pnpm-lock.yaml"
    click docusaurusCfg "https://github.com/nl-design-system/documentatie/blob/main/docusaurus.config.ts"
    click babelCfg "https://github.com/nl-design-system/documentatie/blob/main/babel.config.mjs"
    click tsCfg1 "https://github.com/nl-design-system/documentatie/blob/main/tsconfig.json"
    click tsCfg2 "https://github.com/nl-design-system/documentatie/blob/main/tsconfig.commonjs.json"
    click pkgJSON "https://github.com/nl-design-system/documentatie/blob/main/package.json"
    click navCfg "https://github.com/nl-design-system/documentatie/blob/main/navConfig.ts"
    click sideCfg "https://github.com/nl-design-system/documentatie/blob/main/sidebarConfig.ts"
    click footerCfg "https://github.com/nl-design-system/documentatie/blob/main/footerConfig.ts"
    click prismCfg "https://github.com/nl-design-system/documentatie/blob/main/nldsPrism.ts"
    click rehypeCfg "https://github.com/nl-design-system/documentatie/blob/main/rehype-trailing-slash.ts"
    click GHActions "https://github.com/nl-design-system/documentatie/blob/main/.github/workflows/cd.yml"
    click lint "https://github.com/nl-design-system/documentatie/tree/main/.husky/pre-commit"
    click tests "https://github.com/nl-design-system/documentatie/blob/main/test/e2e/playwright.config.ts"
    click tokenBuild "https://github.com/nl-design-system/documentatie/tree/main/packages/nlds-design-tokens/"
    click docusBuild "https://github.com/nl-design-system/documentatie/blob/main/docusaurus.config.ts"
    click argos "https://github.com/nl-design-system/documentatie/blob/main/test/visual/argos-visual-regression.test.ts"
    click publish "https://github.com/nl-design-system/documentatie/blob/main/.github/workflows/publish.yml"
    click deploy "https://github.com/nl-design-system/documentatie/blob/main/.github/workflows/cd.yml"
    click Compose "https://github.com/nl-design-system/documentatie/blob/main/compose.yaml"
    click Apache "https://github.com/nl-design-system/documentatie/blob/main/httpd.Dockerfile"
    click Vercel "https://github.com/nl-design-system/documentatie/blob/main/vercel.json"
    click Browser "https://github.com/nl-design-system/documentatie/blob/main/static/.nojekyll"
    click Designers "https://github.com/nl-design-system/documentatie/tree/main/packages/nlds-design-tokens/"
    click LocalDocus "https://github.com/nl-design-system/documentatie/blob/main/docusaurus.config.ts"

    %% Styles
    classDef source fill:#cce5ff,stroke:#004085
    classDef build fill:#d4edda,stroke:#155724
    classDef hosting fill:#ffeeba,stroke:#856404
    classDef external fill:#f0f0f0,stroke:#999999,stroke-dasharray: 2 2
    classDef parallelogram shape:parallelogram
    class Repo parallelogram
```
