# vapor/docs architecture

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

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

## Overview

##### Project type and purpose
- This is the “Vapor Documentation” repository: a static-site documentation generator and publisher for the Vapor Swift web framework.
- It uses MkDocs (Python) with a custom theme (Liquid/Leaf) plus Swift scripts to build search indices and redirects. CI/CD is handled via GitHub Actions, and containerization is via Docker Compose.

##### File structure
- Top level:
- Dockerfile + docker-compose.yaml – container definition for local dev and CI builds
- mkdocs.yml – MkDocs config (nav structure, languages, plugins)
- docs/ – Markdown content in multiple languages under subfolders (basics, advanced, deploy, etc.)
- theme/ – Jinja2/Liquid templates, CSS, JS for styling and syntax highlighting
- fixSearchIndex.swift, setUpRedirects.swift – Swift scripts run post-build to patch search index and generate redirects
- .github/workflows – CI jobs: check (lint, build-serve tests) and deploy (build & publish to docs.vapor.codes)
- requirements.txt – Python dependencies for MkDocs plugins and multilingual support

##### README for additional insights
- Local development: `docker compose up` spins up a container with Python3 and MkDocs serving on port 8000.
- Translators add `<filename>.<lang>.md` and update mkdocs.yml under `languages` and `nav_translations`.
- CI pipeline builds all enabled languages and deploys to docs.vapor.codes.

a. Main components
- Developer (local machine)
- Version Control & CI/CD (GitHub + Actions)
- Build Container (Docker Compose image running Python3 + MkDocs + Swift)
- Source Content (docs/ + theme/)
- Build Scripts (fixSearchIndex.swift, setUpRedirects.swift)
- Static Site Output (HTML/CSS/JS)
- Hosting / CDN (docs.vapor.codes)
- End User’s Browser

b. Relationships & interactions
1. Developer pushes commits or pull requests (including translation updates) to GitHub.
2. GitHub Actions “check” workflow:
– Spins up Docker container, installs Python deps, runs `mkdocs build` or `mkdocs serve --check`
– Validates links, front-matter, nav consistency, translation completeness.
3. On merge to main, CI’s “deploy” workflow:
– Builds static site inside container (`mkdocs build`).
– Executes fixSearchIndex.swift to regenerate the search index JSON.
– Executes setUpRedirects.swift to produce redirect templates.
– Publishes the `site/` folder to the hosting target (possibly GitHub Pages or a CDN behind docs.vapor.codes).
4. End user navigates to docs.vapor.codes; CDN serves the pre-built static HTML/CSS/JS.

c. Architectural patterns and design principles
– Static site generation: source (Markdown + templates) → build pipeline → immutable artifacts.
– Containerized reproducible builds (Docker ensures consistency across dev machines and CI).
– CI/CD as code (GitHub Actions) integrates build, test, deploy.
– i18n with file-based content organization and mkdocs.yml language toggles.
– Post-build scripting for non-MkDocs tasks (search indexing, redirect rules) using Swift.

d. Key technologies, frameworks, or libraries
– Docker & Docker Compose
– Python3 + MkDocs + MkDocs-material or custom plugins
– Liquid/Leaf templates for theming
– Swift scripts (fixSearchIndex.swift, setUpRedirects.swift)
– GitHub Actions workflows
– CDN or GitHub Pages for hosting

##### Key reminders
- Be very detailed: capture both the build-time (CI, container, scripts) and run-time (static hosting, browser) aspects.
- Don’t over-complicate: separate into logical components (Source, Build, Publish, Consume) and show interactions.
- Essential architectural elements are visible: i18n content, containerization, CI stages, and hosting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    Dev(["Developer"]):::user
    User(["End User"]):::user

    %% Version Control and CI
    GitHub(("GitHub")):::compute
    subgraph "CI/CD (GitHub Actions)"
        Check["Check Workflow"]:::compute
        Deploy["Deploy Workflow"]:::compute
    end

    %% Source
    subgraph "Source"
        Docs(["docs/ (Markdown)"]):::source
        Theme(["theme/ (Templates & Assets)"]):::source
        Configs["mkdocs.yml<br/>requirements.txt<br/>markdown-link-check-config.yml"]:::source
    end

    %% Container Definition
    DockerCompose["Docker Compose & Dockerfile"]:::compute

    %% Build Container
    subgraph "Build Container"
        MkDocs["Python3 + MkDocs"]:::compute
        SwiftScripts["Swift Scripts<br/>fixSearchIndex.swift<br/>setUpRedirects.swift"]:::script
    end

    %% Output & Hosting
    Site["Static Site Output (site/)"]:::compute
    Hosting(("docs.vapor.codes CDN")):::hosting

    %% Browser
    Browser(["Browser"]):::user

    %% Relationships
    Dev -->|push PR/commit| GitHub
    GitHub -->|triggers| Check
    Check -->|runs in| DockerCompose
    DockerCompose -->|spins up| MkDocs
    DockerCompose -->|runs| SwiftScripts
    GitHub -->|on merge triggers| Deploy
    Deploy -->|builds in| DockerCompose
    DockerCompose -->|executes| MkDocs
    MkDocs -->|generates| Site
    Deploy -->|executes| SwiftScripts
    SwiftScripts -->|patches & redirects| Site
    Site -->|publishes to| Hosting
    Hosting -->|serves static| Browser
    User -->|navigates to| Hosting

    %% Click Events
    click DockerCompose "https://github.com/vapor/docs/tree/main/Dockerfile"
    click DockerCompose "https://github.com/vapor/docs/blob/main/docker-compose.yaml"
    click Configs "https://github.com/vapor/docs/blob/main/mkdocs.yml"
    click Configs "https://github.com/vapor/docs/blob/main/requirements.txt"
    click Configs "https://github.com/vapor/docs/blob/main/markdown-link-check-config.yml"
    click Docs "https://github.com/vapor/docs/tree/main/docs/"
    click Theme "https://github.com/vapor/docs/tree/main/theme/"
    click Theme "https://github.com/vapor/docs/blob/main/theme/scripts/carbon.js"
    click Theme "https://github.com/vapor/docs/blob/main/theme/styles/carbon.css"
    click SwiftScripts "https://github.com/vapor/docs/blob/main/fixSearchIndex.swift"
    click SwiftScripts "https://github.com/vapor/docs/blob/main/setUpRedirects.swift"
    click Check "https://github.com/vapor/docs/blob/main/.github/workflows/check.yml"
    click Deploy "https://github.com/vapor/docs/blob/main/.github/workflows/deploy.yml"
    click GitHub "https://github.com/vapor/docs/tree/main/.github/CODEOWNERS"
    click GitHub "https://github.com/vapor/docs/blob/main/.github/CONTRIBUTING.md"
    click GitHub "https://github.com/vapor/docs/blob/main/.gitignore"
    click DockerCompose "https://github.com/vapor/docs/blob/main/stack.yml"
    click Hosting "https://github.com/vapor/docs/blob/main/googlefc012e5d94cfa05f.html"

    %% Styles
    classDef compute fill:#cbe0fa,stroke:#0366d6,color:#000
    classDef source fill:#d2f8d2,stroke:#22863a,color:#000
    classDef script fill:#ffe2a3,stroke:#d18600,color:#000
    classDef hosting fill:#d0d0d0,stroke:#6a737d,color:#000
    classDef user fill:#f0f0f0,stroke:#555,color:#000
```
