# owasp/top10 architecture

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

- Interactive diagram: https://gitdiagram.com/owasp/top10
- Repository: https://github.com/owasp/top10

## Overview

This repository is not a traditional “running” application but a centralized, version‐controlled document repository for the official OWASP Top 10. Its primary purpose is to organize, maintain, and publish large sets of documentation assets (such as PDFs, PowerPoint presentations, and Markdown files) across several years and languages. It also integrates build automation (via scripts, Makefiles, mkdocs configuration, etc.) to generate a website (static site content), and supports community engagement through GitHub configuration files and contribution guidelines.

##### Main Components & Their Roles
- Repository Content – This is the “heart” of the project. It includes:
– Yearly directories (2013, 2017, 2021, 2024) that contain the different versions of the Top 10 documentation.
– Language-specific folders within years (e.g., “en”, “es”, “ja”, etc.) that hold translated Markdown files and assets.
– Additional directories like “archives”, “osib”, “docs”, and “generated” that provide supplementary materials (cheatsheets, legacy documents, migration guides, etc.).
- Build & Automation Scripts – These components include:
– Build scripts (Makefile, shell scripts in the scripts/ directory) and Python scripts (for generating cheat sheets, RSS feeds, and sites).
– Configuration files such as mkdocs.yml and requirements.txt that drive the static site generation and content build pipelines.
- CI/CD & Repository Management – The repository also contains:
– GitHub workflow configuration (.github folder) and code quality/linting configurations (.gitignore, .markdownlint.json, etc.).
– Contribution guidelines (CONTRIBUTING.md, CODE_OF_CONDUCT.md) and project workspace files.
- Generated Site Output – The outcome of the build process is stored in:
– The “site” directory and possibly similar output in “generated”, representing the static website that is eventually deployed.
- External Integrations – The project integrates with:
– GitHub Issues and community contribution channels (as seen in the README and leadership contact details).
– External references like the OWASP Top 10 Project Page and Summit Outcomes.

##### Relationships & Data Flow
- The content stored in various directories (Docs, Presentations, Data) is the raw material for the website.
- The build automation (using mkdocs, Makefile, and other scripts) reads from these content directories, transforms and bundles them into static pages.
- The CI/CD pipelines (configured via GitHub and potentially external integrations) keep the content validated, linted, and eventually pushed/deployed.
- End users access the published content via the generated static site.
- Community and leadership links (via the README) indicate feedback flows back into the repository through GitHub issues or contributions.

##### Architectural Patterns & Design Principles
- Static Content Generation – The project leverages a static site generation approach (using mkdocs) to present documentation in an organized manner.
- Content Modularity – Each year and language is treated as a separate module that can be built and updated independently.
- Automation & Integration – Build scripts and automation ensure that content is regularly updated, validated, and deployed.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Repository Content
    subgraph "Repository Content"
        RC1["Year 2013"]:::repo
        RC2["Year 2017"]:::repo
        RC3["Year 2021"]:::repo
        RC4["Year 2024"]:::repo
        RC2a["2017/en"]:::repoSub
        RC2b["2017/es"]:::repoSub
        RC2c["2017/ja"]:::repoSub
        RC5["archives"]:::repo
        RC6["osib"]:::repo
        RC7["docs"]:::repo
    end

    %% Build & Automation Scripts
    subgraph "Build & Automation Scripts"
        BA1["Makefile"]:::build
        BA2["scripts"]:::build
        BA3["mkdocs.yml"]:::config
        BA4["requirements.txt"]:::config
    end

    %% CI/CD & Repository Management
    subgraph "CI/CD & Repository Management"
        CI1[".github"]:::ci
        CI2[".gitignore"]:::ci
        CI3[".markdownlint.json"]:::ci
        CI4[".textlintrc"]:::ci
        CI5["CONTRIBUTING.md"]:::ci
        CI6["CODE_OF_CONDUCT.md"]:::ci
    end

    %% Generated Static Site Output
    subgraph "Generated Static Site Output"
        GS1["site"]:::generated
        GS2["generated"]:::generated
    end

    %% External Integrations
    subgraph "External Integrations"
        EX1["README.md"]:::external
        EX2["Project.code-workspace"]:::external
        EX3["package.json"]:::external
    end

    %% Relationships & Data Flow
    RC2 ---|"raw_to_build"| BA3
    BA2 ---|"executes"| BA3
    BA4 ---|"dependency"| BA3
    BA3 ---|"builds_static"| GS1
    CI1 ---|"CI_checks"| RC2
    CI1 ---|"CI_deploys"| GS1
    EX1 ---|"feedback"| RC2

    %% Click Events for Repository Content
    click RC1 "https://github.com/owasp/top10/tree/master/2013"
    click RC2 "https://github.com/owasp/top10/tree/master/2017"
    click RC3 "https://github.com/owasp/top10/tree/master/2021"
    click RC4 "https://github.com/owasp/top10/tree/master/2024"
    click RC2a "https://github.com/owasp/top10/tree/master/2017/en"
    click RC2b "https://github.com/owasp/top10/tree/master/2017/es"
    click RC2c "https://github.com/owasp/top10/tree/master/2017/ja"
    click RC5 "https://github.com/owasp/top10/tree/master/archives"
    click RC6 "https://github.com/owasp/top10/tree/master/osib"
    click RC7 "https://github.com/owasp/top10/tree/master/docs"

    %% Click Events for Build & Automation Scripts
    click BA1 "https://github.com/owasp/top10/tree/master/Makefile"
    click BA2 "https://github.com/owasp/top10/tree/master/scripts"
    click BA3 "https://github.com/owasp/top10/blob/master/mkdocs.yml"
    click BA4 "https://github.com/owasp/top10/blob/master/requirements.txt"

    %% Click Events for CI/CD & Repository Management
    click CI1 "https://github.com/owasp/top10/blob/master/.github"
    click CI2 "https://github.com/owasp/top10/blob/master/.gitignore"
    click CI3 "https://github.com/owasp/top10/blob/master/.markdownlint.json"
    click CI4 "https://github.com/owasp/top10/blob/master/.textlintrc"
    click CI5 "https://github.com/owasp/top10/blob/master/CONTRIBUTING.md"
    click CI6 "https://github.com/owasp/top10/blob/master/CODE_OF_CONDUCT.md"

    %% Click Events for Generated Static Site Output
    click GS1 "https://github.com/owasp/top10/tree/master/2021/site"
    click GS2 "https://github.com/owasp/top10/tree/master/generated"

    %% Click Events for External Integrations
    click EX1 "https://github.com/owasp/top10/blob/master/README.md"
    click EX2 "https://github.com/owasp/top10/blob/master/Project.code-workspace"
    click EX3 "https://github.com/owasp/top10/blob/master/package.json"

    %% Styles
    classDef repo fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef repoSub fill:#d6f5d6,stroke:#333,stroke-width:2px;
    classDef build fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef config fill:#b0e0e6,stroke:#333,stroke-width:2px;
    classDef ci fill:#fdd49e,stroke:#333,stroke-width:2px;
    classDef generated fill:#d4a6c8,stroke:#333,stroke-width:2px;
    classDef external fill:#f8cce0,stroke:#333,stroke-width:2px;
```
