# assured/wstg architecture

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

- Interactive diagram: https://gitdiagram.com/assured/wstg
- Repository: https://github.com/assured/wstg

## Overview

##### Project type and purpose
- This is a documentation‐centric repository that powers the OWASP Web Security Testing Guide (WSTG).
- It isn’t a “running” full‐stack app; rather it’s a static‐site and multi‐format build pipeline for a large body of Markdown content.
- Purpose: maintain and publish the WSTG as HTML (via GitHub Pages), PDF, and machine‐readable JSON.

##### File structure
- Top‐level content directories:
- document/ – the core guide content in Markdown, organized by chapters and sections
- checklist/ – JSON and Excel assets for the WSTG checklist
- template/ – sample testing templates
- Configuration and build orchestrators:
- .devcontainer/ – Dockerfile and VS Code devcontainer.json for local development
- .github/ – CI/CD workflows, linting configs, PDF/JSON build scripts, and `www` site artifacts
- Build metadata: package.json, style_guide.md, Testing_for_APIs.md
- Key patterns: single “monorepo” holding source content + CI/CD code + output artifacts, using scripts and containers for reproducible builds.

##### README for additional insights
- Describes the guide’s purpose, versioning scheme, linking conventions, contribution instructions.
- Mentions that releases produce HTML, PDF, and JSON outputs (via GitHub Actions).
- No “runtime” components: it’s purely a content publication pipeline.

##### Main components
a. Content Store
– Markdown files in document/, checklist/, template/
– Style guide and asset directories
b. Local Development Environment
– Developer workstation + VS Code DevContainer
– Container: Node.js, linting tools, build scripts installed
c. CI/CD Orchestrator (GitHub Actions)
– Workflows: md‑lint‑check, md‑link‑check, build‑json, build‑pdf, www‑deploy
– Triggers on push, PRs, and releases
d. Build Script Layer
– make-json.sh → converts Markdown to JSON
– make-pdf.sh → assembles PDF via pandoc/PrinceXML or similar
– NPM scripts invoked by workflows
e. Artifact Repository / Deployment
– .github/www/ → static HTML fragments for GitHub Pages
– PDF files stored in release assets
– JSON published for machine consumption or API use
f. External Services
– GitHub (repo, Actions, Pages)
– Slack/Google Groups for chat
– npm registry (if any dependencies)

##### Relationships and interactions
1. Author edits Markdown locally (DevContainer) → commits to GitHub
2. GitHub Actions pick up changes → run linting workflows → fail fast on errors
3. On successful checks or tagged release → run build-json and build-pdf
4. Generated JSON and PDF pushed to release assets
5. Static site content (.github/www) updated and deployed to GitHub Pages

##### Architectural patterns and design principles
- GitOps: everything version controlled, build/deploy via code
- Containerized local dev for consistency
- Single‐source‐of‐truth for content (Markdown)
- Multi‐format derivation (JSON, PDF, HTML) via scripting layer
- Separation of concerns: content vs. linting vs. build vs. deployment

##### Essential elements
- Callouts for key technologies (Markdown, Docker, Node.js, GitHub Actions, pandoc/PDF tool, GitHub Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Author(("Author")):::external
    GitHubRepo(["GitHub Repo"]):::external
    GitHubPages(["GitHub Pages"]):::external
    GitHubReleases(["GitHub Releases"]):::external

    %% Local Development
    subgraph "Local Development"
        Editor["Editor (VS Code)"]:::process
        Dockerfile["Dockerfile"]:::process
        DevContainerConfig["devcontainer.json"]:::process
    end

    %% Content Store
    subgraph "Content Store"
        Document["document/"]:::content
        ChecklistDir["checklist/"]:::content
        Template["template/"]:::content
        StyleGuide["style_guide.md"]:::content
        TestingAPIs["Testing_for_APIs.md"]:::content
    end

    %% CI/CD Workflows
    subgraph "CI/CD (GitHub Actions)"
        mdLint["md-lint-check.yml"]:::ci
        mdLink["md-link-check.yml"]:::ci
        mdTextlint["md-textlint-check.yml"]:::ci
        buildJsonWF["build-json.yml"]:::ci
        buildPdfWF["build-pdf.yml"]:::ci
        wwwLatest["www_latest_update.yml"]:::ci
        wwwStable["www_stable_update.yml"]:::ci
    end

    %% Build Scripts
    subgraph "Build Scripts"
        MakeJson["make-json.sh"]:::process
        MakePdf["make-pdf.sh"]:::process
        NpmScripts["package.json"]:::process
    end

    %% Artifacts and Deployment
    subgraph "Deployment & Artifacts"
        StaticSite[".github/www/"]:::artifact
        JSONAsset["checklist.json"]:::artifact
        ExcelAsset["WSTG-Checklist_v4.2.xlsx"]:::artifact
        PDFAsset["guide.pdf"]:::artifact
    end

    %% Flows
    Author --> Editor
    Editor --> GitHubRepo
    Editor --> Document
    Editor --> ChecklistDir
    Editor --> Template
    Editor --> StyleGuide
    Editor --> TestingAPIs
    Editor --> Dockerfile
    Editor --> DevContainerConfig

    GitHubRepo -->|triggers| mdLint
    GitHubRepo -->|triggers| mdLink
    GitHubRepo -->|triggers| mdTextlint

    mdLint -->|on success| buildJsonWF
    mdLink -->|on success| buildJsonWF
    mdTextlint -->|on success| buildJsonWF

    buildJsonWF -->|invokes| MakeJson
    buildPdfWF -->|invokes| MakePdf
    buildJsonWF -->|via npm| NpmScripts
    buildPdfWF -->|via npm| NpmScripts

    MakeJson --> JSONAsset
    MakeJson --> StaticSite
    MakePdf --> PDFAsset
    MakePdf --> StaticSite

    wwwLatest --> StaticSite
    wwwStable --> StaticSite

    JSONAsset --> GitHubReleases
    ExcelAsset --> GitHubReleases
    PDFAsset --> GitHubReleases
    StaticSite --> GitHubPages

    %% Click Events
    click Document "https://github.com/assured/wstg/tree/master/document/"
    click ChecklistDir "https://github.com/assured/wstg/tree/master/checklist/"
    click Template "https://github.com/assured/wstg/tree/master/template/"
    click StyleGuide "https://github.com/assured/wstg/blob/master/style_guide.md"
    click TestingAPIs "https://github.com/assured/wstg/blob/master/Testing_for_APIs.md"
    click Dockerfile "https://github.com/assured/wstg/tree/master/.devcontainer/Dockerfile"
    click DevContainerConfig "https://github.com/assured/wstg/blob/master/.devcontainer/devcontainer.json"
    click mdLint "https://github.com/assured/wstg/blob/master/.github/workflows/md-lint-check.yml"
    click mdLink "https://github.com/assured/wstg/blob/master/.github/workflows/md-link-check.yml"
    click mdTextlint "https://github.com/assured/wstg/blob/master/.github/workflows/md-textlint-check.yml"
    click buildJsonWF "https://github.com/assured/wstg/blob/master/.github/workflows/build-json.yml"
    click buildPdfWF "https://github.com/assured/wstg/blob/master/.github/workflows/build-pdf.yml"
    click wwwLatest "https://github.com/assured/wstg/blob/master/.github/workflows/www_latest_update.yml"
    click wwwStable "https://github.com/assured/wstg/blob/master/.github/workflows/www_stable_update.yml"
    click MakeJson "https://github.com/assured/wstg/blob/master/.github/scripts/make-json.sh"
    click MakePdf "https://github.com/assured/wstg/blob/master/.github/pdf/scripts/make-pdf.sh"
    click NpmScripts "https://github.com/assured/wstg/blob/master/package.json"
    click StaticSite "https://github.com/assured/wstg/tree/master/.github/www/"
    click JSONAsset "https://github.com/assured/wstg/blob/master/checklist/checklist.json"
    click ExcelAsset "https://github.com/assured/wstg/blob/master/checklist/WSTG-Checklist_v4.2.xlsx"

    %% Styles
    classDef content fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72;
    classDef process fill:#D5F5E3,stroke:#28B463,color:#196F3D;
    classDef ci fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef artifact fill:#FADBD8,stroke:#E74C3C,color:#78281F;
    classDef external fill:#E8E8E8,stroke:#AAAAAA,color:#333333;
```
