# github/docs architecture

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

- Interactive diagram: https://gitdiagram.com/github/docs
- Repository: https://github.com/github/docs

## Overview

##### Project type and purpose
- This is a full-stack documentation website (docs.github.com) built with Next.js (React + Node/TypeScript).
- It ingests Markdown content (in content/, data/ and assets/), transforms it via content-render, content-linter, and other pipelines, then serves it through a Next.js server with dynamic API routes (article-api, REST, GraphQL, search, audit-logs, secret-scanning, webhooks, etc.).
- CI/CD is orchestrated by GitHub Actions, and production runs in Docker/Kubernetes behind a CDN (Fastly).

##### Main components
a. Source content & data
- content/, data/, assets/: Markdown, YAML, CSV source files
- data-directory, automated-pipelines, ghes-releases, etc.: scripts to validate/generate derived JSON/HTML
b. Build & CI/CD
- .github/workflows: lint, test, build, deploy pipelines
- Dockerfile + docker-compose + .devcontainer: containerize for local dev and staging/prod
c. Core application
- Next.js frontend (src/frame + src/pages): React pages and dynamic route handlers
- API routes (under src/*-api, src/rest, src/graphql, src/search, etc.): serverless/Express-style functions
- Shared libraries (src/content-render, src/content-linter, src/assets, src/data-directory)
d. Infrastructure & deployment
- config/kubernetes: manifests for webapp Deployment + Service
- config/moda: feature-flag & environment configs
- External services: Elasticsearch cluster for site search; Fastly for CDN & remote JSON caching; optional S3/minio for assets
e. Tests & monitoring
- src/tests, fixtures, vitest.config.ts: unit, integration, e2e (Playwright)
- observability: StatsD, error handling, failbot
- workflows: slack alerts, dead link checks

##### Component interactions
- Developer → GitHub → GitHub Actions (CI): runs content-linter, tests, builds artifacts → pushes Docker image
- Kubernetes (Production & Staging): pulls image → runs Next.js server + API routes
- CDN (Fastly) sits in front of the Next.js origin, caching both pages and remote JSON endpoints
- Next.js server’s API routes query:
- local JSON (generated under public or via remotejson) for content, data, assets
- Elasticsearch for general and AI search
- static JSON schemas for REST/GraphQL docs
- Client browsers fetch pages + assets via CDN; JS hydration for interactive features

##### Architectural patterns & principles
- Monorepo with clear separation of concerns: content, data pipelines, services, frontend
- “Headless CMS” approach: Markdown + JSON → API → page rendering
- Next.js Server-Side Rendering + Dynamic Routes for versioned docs
- Feature-flag driven code (config/moda, useFeatureFlags hook)
- Microservices-within-Next.js: each subfolder under src/*-api or src/* acts as its own API endpoint
- Kubernetes + GitOps for deployments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content & Data Layer
    subgraph "Content & Data Layer"
        ContentStore["Content Store\n(Markdown, data, assets)"]:::content
        DataStore["Data Store\n(YAML/JSON/CSV)"]:::content
        Assets["Assets\n(Images, static files)"]:::content
        subgraph "Pipelines"
            CR["content-render"]:::content
            CL["content-linter"]:::content
            DD["data-directory"]:::content
            AP["automated-pipelines"]:::content
            GHES["ghes-releases"]:::content
        end
    end

    %% Application Layer
    subgraph "Application Layer"
        NextServer["Next.js Server\n(Frontend & API Routes)"]:::compute

        subgraph "Frontend"
            Frame["Frame & Layout"]:::compute
            Pages["Pages\n([version]/[product] routes)"]:::compute
            Landings["Static Landings"]:::compute
            Versions["Version Picker"]:::compute
            Languages["Language Middleware"]:::compute
        end

        subgraph "API Services"
            ArticleAPI["Article API"]:::compute
            RESTAPI["REST API"]:::compute
            GraphQLAPI["GraphQL API"]:::compute
            SearchAPI["Search API"]:::compute
            AuditAPI["Audit Logs API"]:::compute
            Webhooks["Webhooks API"]:::compute
            SecretScan["Secret Scanning API"]:::compute
        end

        subgraph "Shared Libraries"
            CR2["content-render"]:::compute
            CL2["content-linter"]:::compute
            DD2["data-directory"]:::compute
        end

        subgraph "Observability & Middleware"
            Observability["Observability\n(StatsD, failbot)"]:::compute
            Shield["Shielding Middleware"]:::compute
            Tracking["Tracking Middleware"]:::compute
        end

        subgraph "Tests & Monitoring"
            Tests["Tests\n(Playwright, Vitest)"]:::compute
            Fixtures["Fixtures"]:::compute
            Vitest["Vitest Config"]:::compute
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        CI["GitHub Actions CI/CD"]:::infra
        CQ["Custom Actions"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DC["docker-compose.yaml"]:::infra
        DevContainer[".devcontainer"]:::infra
        K8s["Kubernetes Cluster"]:::infra
        Moda["Feature Flags"]:::infra
        CDN["CDN / Fastly"]:::external
        ES["Elasticsearch Cluster"]:::external
        S3["S3 / Minio"]:::external
    end

    %% Data & Build Flows
    ContentStore --> CR --> NextServer
    DataStore --> DD --> NextServer
    Assets --> NextServer
    CL --> NextServer

    %% Developer & CI/CD
    Developer["Developer Commit"]:::external --> CI
    CI --> Dockerfile
    CI --> DC
    CI --> Tests
    CI --> CQ
    CQ --> Tests
    CI -->|build image| K8s

    %% Deployment
    K8s --> NextServer

    %% Client Requests
    Client["Client Browser"]:::external --> CDN
    CDN --> NextServer
    NextServer -->|serves pages & JSON| CDN

    %% API calls
    NextServer --> ArticleAPI
    NextServer --> RESTAPI
    NextServer --> GraphQLAPI
    NextServer --> SearchAPI
    NextServer --> AuditAPI
    NextServer --> Webhooks
    NextServer --> SecretScan

    SearchAPI --> ES
    NextServer --> S3

    %% Shared libs & middleware usage
    NextServer --> CR2
    NextServer --> CL2
    NextServer --> DD2
    NextServer --> Observability
    NextServer --> Shield
    NextServer --> Tracking

    %% Testing
    CI --> Fixtures
    CI --> Vitest

    %% Classes and Styles
    classDef content fill:#cce5ff,stroke:#004085,color:#004085
    classDef compute fill:#d4edda,stroke:#155724,color:#155724
    classDef infra fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef external fill:#fff3cd,stroke:#856404,color:#856404

    %% Click Events
    click ContentStore "https://github.com/github/docs/tree/main/content/"
    click DataStore "https://github.com/github/docs/tree/main/data/"
    click Assets "https://github.com/github/docs/tree/main/assets/"
    click CR "https://github.com/github/docs/tree/main/src/content-render/"
    click CL "https://github.com/github/docs/tree/main/src/content-linter/"
    click DD "https://github.com/github/docs/tree/main/src/data-directory/"
    click AP "https://github.com/github/docs/tree/main/src/automated-pipelines/"
    click GHES "https://github.com/github/docs/tree/main/src/ghes-releases/"
    click Frame "https://github.com/github/docs/tree/main/src/frame/"
    click Pages "https://github.com/github/docs/tree/main/src/pages/"
    click Landings "https://github.com/github/docs/tree/main/src/landings/"
    click Versions "https://github.com/github/docs/tree/main/src/versions/"
    click Languages "https://github.com/github/docs/tree/main/src/languages/"
    click ArticleAPI "https://github.com/github/docs/tree/main/src/article-api/"
    click RESTAPI "https://github.com/github/docs/tree/main/src/rest/"
    click GraphQLAPI "https://github.com/github/docs/tree/main/src/graphql/"
    click SearchAPI "https://github.com/github/docs/tree/main/src/search/"
    click AuditAPI "https://github.com/github/docs/tree/main/src/audit-logs/"
    click Webhooks "https://github.com/github/docs/tree/main/src/webhooks/"
    click SecretScan "https://github.com/github/docs/tree/main/src/secret-scanning/"
    click Observability "https://github.com/github/docs/tree/main/src/observability/"
    click Shield "https://github.com/github/docs/tree/main/src/shielding/"
    click Tracking "https://github.com/github/docs/tree/main/src/tracking/"
    click Tests "https://github.com/github/docs/tree/main/src/tests/"
    click Fixtures "https://github.com/github/docs/tree/main/src/fixtures/"
    click Vitest "https://github.com/github/docs/blob/main/vitest.config.ts"
    click CI "https://github.com/github/docs/tree/main/.github/workflows/"
    click CQ "https://github.com/github/docs/tree/main/.github/actions/"
    click Dockerfile "https://github.com/github/docs/tree/main/Dockerfile"
    click DC "https://github.com/github/docs/blob/main/docker-compose.yaml"
    click DevContainer "https://github.com/github/docs/tree/main/.devcontainer/"
    click K8s "https://github.com/github/docs/tree/main/config/kubernetes/"
    click Moda "https://github.com/github/docs/tree/main/config/moda/"
```
