# vapor/api-docs architecture

> Architecture diagram of the GitHub repository vapor/api-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/api-docs
- Repository: https://github.com/vapor/api-docs

## Overview

##### Project type and purpose
- This is an open-source tooling project whose sole responsibility is to generate and publish the API documentation for Vapor-based repos.
- It does not contain a customer-facing application; rather, it provides Swift scripts (generate-api-docs.swift, generate-package-api-docs.swift) and GitHub Actions workflows that, on every release in a Vapor repo, pull this tool in and run it to produce updated docs.

##### File structure
- .github/workflows/build-and-deploy-docs-workflow.yml & deploy-api-docs.yml – define CI/CD pipeline steps when a new release is cut.
- generate-api-docs.swift & generate-package-api-docs.swift – core Swift scripts that crawl repositories, render Markdown/DocC, and emit static HTML.
- index.html, error.html, theme-settings.json, images/ – static assets and theme configuration used by the generated docs site.
- stack.yaml – configuration for building/running the Swift (or Haskell-stack) environment to execute the scripts.

##### README for additional insights
- The README confirms that on each tagged release in any Vapor repo, a GitHub Action boots this repo’s scripts on a server, generates the docs, and publishes them to https://api.vapor.codes.

##### Main components & their interactions
a. Source Repositories (any Vapor project)
b. GitHub Actions workflows in each source repo (on “release” event)
c. This API-docs-generator repo – checked out by the workflow
d. Swift scripting environment (Docker/Mac builder, installed via stack.yaml)
e. Documentation Server / Hosting (the target of deploy step; serves at api.vapor.codes)
f. End Users (developers browsing the API docs site)

Data Flow & Sequence:
1. Developer creates a new Release tag in a Vapor repo.
2. GitHub Actions in that repo triggers the “build-and-deploy-docs-workflow.”
3. The workflow clones this api-docs-generator repo.
4. It spins up the Swift runtime (via stack.yaml) and runs generate-api-docs.swift (or generate-package-api-docs.swift).
5. Scripts produce static HTML (using index.html, theme-settings.json, images/, error.html).
6. The “deploy-api-docs.yml” job uploads the static site to the Documentation Server (e.g., S3/CloudFront or custom host).
7. End users view fresh docs at api.vapor.codes.

##### Key architectural patterns and design principles
- CI/CD pipeline: separation of “build” (generate static assets) and “deploy” phases.
- Immutable infrastructure principle: on each release, you spin up a fresh environment via GH Actions.
- Static site generation: all docs are rendered ahead-of-time, no server-side rendering at request time.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Vapor Ecosystem"
    VSR["Vapor Source Repos"]
  end

  subgraph "CI/CD Pipeline"
    GA1["Build & Deploy Workflow"]:::ci
    GA2["Deploy Docs Job"]:::ci
    ADR["api-docs-generator Repo"]:::ci
    G1["generate-api-docs.swift"]:::ci
    G2["generate-package-api-docs.swift"]:::ci
    SSE["Swift Scripting Environment"]:::ci
    README["README.md"]:::code
  end

  subgraph "Static Content"
    INDEX["index.html"]:::static
    ERROR["error.html"]:::static
    THEME["theme-settings.json"]:::static
    IMAGES["images/"]:::static
  end

  DOC["Documentation Hosting"]:::infra
  USERS["End Users (API Consumers)"]

  VSR -->|"on release tag"| GA1
  GA1 -->|"clones repo"| ADR
  ADR --> G1
  ADR --> G2
  G1 -->|"executes in"| SSE
  G2 -->|"executes in"| SSE
  SSE -->|"generates static HTML"| GA2
  GA2 -->|"deploys site"| DOC
  DOC -->|"serves docs"| USERS

  SSE --> INDEX
  SSE --> ERROR
  SSE --> THEME
  SSE --> IMAGES
  SSE --> README

  click GA1 "https://github.com/vapor/api-docs/blob/main/.github/workflows/build-and-deploy-docs-workflow.yml"
  click GA2 "https://github.com/vapor/api-docs/blob/main/.github/workflows/deploy-api-docs.yml"
  click G1 "https://github.com/vapor/api-docs/blob/main/generate-api-docs.swift"
  click G2 "https://github.com/vapor/api-docs/blob/main/generate-package-api-docs.swift"
  click INDEX "https://github.com/vapor/api-docs/blob/main/index.html"
  click ERROR "https://github.com/vapor/api-docs/blob/main/error.html"
  click THEME "https://github.com/vapor/api-docs/blob/main/theme-settings.json"
  click IMAGES "https://github.com/vapor/api-docs/tree/main/images/"
  click SSE "https://github.com/vapor/api-docs/blob/main/stack.yaml"
  click README "https://github.com/vapor/api-docs/blob/main/README.md"
  click ADR "https://github.com/vapor/api-docs/tree/main//"

  classDef ci fill:#c6f6d5,stroke:#2f855a
  classDef static fill:#bee3f8,stroke:#2b6cb0
  classDef infra fill:#fbd38d,stroke:#d69e2e
  classDef code fill:#e2e8f0,stroke:#a0aec0
```
