# owasp/www-project-web-security-testing-guide architecture

> Architecture diagram of the GitHub repository owasp/www-project-web-security-testing-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/owasp/www-project-web-security-testing-guide
- Repository: https://github.com/owasp/www-project-web-security-testing-guide

## Overview

##### Project Type & Purpose
- This is a Jekyll‐based static site generator for the OWASP Web Security Testing Guide (WSTG) landing page on owasp.org.
- It pulls in Markdown content (versioned under folders like `latest/`, `stable/`, `v41/`, `v42/`), data files (`_data/*.yaml`), layouts/includes (`_includes/`), config (`_config.yml`), and assets (`assets/`), then produces HTML/CSS/JS for deployment.

##### File Structure & Architectural Patterns
- **Content Directories**: `latest/`, `stable/`, `v41/`, `v42/` each contain Markdown chapters and front matter (info.md, index.md).
- **Templates & Includes**: `_includes/` (header, nav, breadcrumbs), default layouts in Jekyll’s `_layouts/` (implied).
- **Data Layer**: `_data/` YAML/JSON files feed the templates with dynamic sidebars, version lists, attributions.
- **Assets Pipeline**: `assets/` holds images, archived downloads, CSS/JS handled by Jekyll or plugins.
- **Configuration**: `Gemfile` + `bundle install`, `_config.yml` define plugins, base URL, build options.
- **CI/CD**: `.github/workflows/pr_comment.yml` integrates with GitHub Actions for PR checks; additional workflows will handle build & deployment.

##### Key Components
a. **Developer Environment**
- Local machine with Ruby, Bundler, Jekyll CLI.
- Source code (Markdown, templates, config).
b. **Version Control & CI**
- GitHub repo triggers Actions on push/PR.
- CI job: `bundle install` → `jekyll build` → artifact verification.
c. **Build Engine**
- Jekyll (Ruby) + any plugins (Liquid templating, data ingestion).
- Input: content + data + templates.
- Output: static site under `_site/`.
d. **Deployment/Hosting**
- GitHub Pages or OWASP infrastructure (could be a static‐hosting bucket + CDN).
- Delivery via CDN (e.g., CloudFront or Netlify).
e. **End Users**
- Browsers requesting HTML, CSS, JS, images.

##### Relationships & Data Flow
- Developer makes changes → `git push` → GitHub Actions → Jekyll build → static artifacts → deploy to hosting → CDN cache → end user.
- Data/_data YAML → fed into templates → generates navigation menus, version selectors.
- Assets copied directly into output and served.

##### Important Architectural Principles
- **Separation of Concerns**: content (Markdown) vs presentation (layouts/includes) vs data (YAML).
- **Static Generation**: no backend runtime; build‐time assembly.
- **CI/CD Pipeline**: ensures validity of link references, layout consistency, correct asset paths.
- **Extensibility Points**: Jekyll plugins, Liquid includes for new sections or versions.

##### Must‐Have Elements
- Annotations for technologies: “Ruby + Jekyll”, “Liquid templates”, “GitHub Actions”, “GitHub Pages/CDN”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        DEV["Local Machine<br/>Ruby, Bundler, Jekyll CLI"]:::developer
    end

    %% Version Control & CI
    subgraph "Version Control & CI"
        GH["GitHub Repository"]:::developer
        CI["GitHub Actions CI<br/>bundle install → jekyll build"]:::ci
        PR["PR Comment Bot<br/>(pr_comment.yml)"]:::ci
        GH -->|push / PR| CI
        CI -->|comment trigger| PR
    end

    %% Build Engine
    subgraph "Build Engine"
        BE["Jekyll Build<br/>Ruby + Liquid Plugins"]:::build
        subgraph "Content Layer"
            MD1["latest/"]:::build
            MD2["stable/"]:::build
            MD3["v41/"]:::build
            MD4["v42/"]:::build
            MD5["index.md, info.md,<br/>leaders.md,<br/>tab_downloads.md,<br/>tab_faq.md"]:::build
        end
        subgraph "Data Layer"
            D1["_data/latest.yaml"]:::build
            D2["_data/stable.yaml"]:::build
            D3["_data/v41.yaml"]:::build
            D4["_data/v42.yaml"]:::build
            D5["_data/ow_attributions.json"]:::build
        end
        subgraph "Templates & Includes"
            T1["_includes/banner.html"]:::build
            T2["_includes/breadcrumb.html"]:::build
            T3["_includes/navigation.html"]:::build
        end
        subgraph "Assets Pipeline"
            A1["assets/archive/"]:::build
            A2["assets/images/"]:::build
        end
        subgraph "Configuration"
            C1["Gemfile"]:::build
            C2["_config.yml"]:::build
        end
        BE -->|outputs| SITE["_site/"]:::build
        MD1 -->|content| BE
        MD2 -->|content| BE
        MD3 -->|content| BE
        MD4 -->|content| BE
        MD5 -->|content| BE
        D1 -->|data| BE
        D2 -->|data| BE
        D3 -->|data| BE
        D4 -->|data| BE
        D5 -->|data| BE
        T1 -->|templates| BE
        T2 -->|templates| BE
        T3 -->|templates| BE
        A1 -->|assets| BE
        A2 -->|assets| BE
        C1 -->|config| BE
        C2 -->|config| BE
    end

    %% Deployment & Hosting
    subgraph "Deployment & Hosting"
        HOST["GitHub Pages / OWASP Infra"]:::hosting
        CDN["CDN (CloudFront / Netlify)"]:::hosting
        SITE -->|deploy| HOST
        HOST -->|cache & serve| CDN
    end

    %% End Users
    subgraph "End Users"
        USER["Browser"]:::user
        CDN -->|HTTP requests| USER
    end

    %% Main Flow
    DEV -->|commit & push| GH
    CI -->|build trigger| BE

    %% Click Events
    click MD1 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/latest/"
    click MD2 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/stable/"
    click MD3 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/v41/"
    click MD4 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/v42/"
    click MD5 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/index.md"
    click D1 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_data/latest.yaml"
    click D2 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_data/stable.yaml"
    click D3 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_data/v41.yaml"
    click D4 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_data/v42.yaml"
    click D5 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_data/ow_attributions.json"
    click T1 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_includes/banner.html"
    click T2 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_includes/breadcrumb.html"
    click T3 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_includes/navigation.html"
    click A1 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/assets/archive/"
    click A2 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/assets/images/"
    click C1 "https://github.com/owasp/www-project-web-security-testing-guide/tree/master/Gemfile"
    click C2 "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/_config.yml"
    click PR "https://github.com/owasp/www-project-web-security-testing-guide/blob/master/.github/workflows/pr_comment.yml"

    %% Styles
    classDef developer fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef ci fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef build fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef hosting fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef user fill:#f0f0f0,stroke:#333,stroke-width:1px
```
