# security-alliance/frameworks architecture

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

- Interactive diagram: https://gitdiagram.com/security-alliance/frameworks
- Repository: https://github.com/security-alliance/frameworks

## Overview

##### Main Components
a. Content Layer
- Source Markdown files under `src/` (chapter content, SUMMARY.md, README.md)
- Configuration files (book.toml, prebuild.sh, serve.sh)
b. Build Engine
- mdBook core (installed via Cargo: `mdbook`, `mdbook-admonish`, `mdbook-catppuccin`)
- Custom plugin: `plugin/mdbook-metadata` (Rust crate wrapping `mdbook-metadata` commands)
- Theme assets under `theme/` (CSS, JS, Handlebars templates)
c. CI/CD & Validation
- GitHub Actions workflows (`.github/workflows/md-lint.yaml`, `spell-check.yml`)
- Pre-build script (`prebuild.sh`) ensures environment consistency
d. Deployment
- Vercel platform for hosting (triggered by git pushes / Vercel build script `vercel_build.sh`)
- Production domain planned (`frameworks.securityalliance.org`)
e. Collaboration/GitHub
- GitHub repo as single source of truth
- Fork & PR workflow (branching model: `develop` → `main`)
- Issue templates & pull‐request templates for contribution guidance

##### Relationships & Data Flow
a. Authoring: Contributors commit Markdown + config files to GitHub.
b. CI Validation: GitHub Actions run linters/spell-checkers on new commits/PRs.
c. Build Pipeline:
- `prebuild.sh` sets up environment
- mdBook core invokes plugins (`mdbook-admonish`, `mdbook-catppuccin`, `mdbook-metadata`)
- Theme templates & assets are applied to generated HTML.
- Output is a static site in `book/` directory
d. Deployment: The static output is pushed to Vercel (via `vercel_build.sh` or Vercel integration), which serves it under the live URLs.
e. Local Preview: Developers run `./serve.sh` (which wraps mdBook serve plus theme/plugin loading) to preview on localhost.

##### Architectural Patterns & Principles
- Modular pipeline: core engine + plugins + themes
- Content‐as‐data: markdown sources drive site generation
- GitOps: all changes flow through PRs, CI, and automated deploy
- Separation of concerns:
- Content (src/)
- Presentation (theme/)
- Build logic (mdBook + plugins)
- Infrastructure (Vercel, CI workflows)

##### Essential Elements
- Components:
- GitHub Repository (with branches)
- CI/CD Workflows (lint, spell-check)
- prebuild.sh & serve.sh scripts
- mdBook Core + Plugins + Themes
- Static Site Output (`book/` folder)
- Vercel Deployment & Live URLs
- Clear layering: Source → Build → Validation → Deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        src["src/ (Markdown)"]:::content
        summary["src/SUMMARY.md"]:::content
        readme["src/README.md"]:::content
        booktoml["book.toml"]:::content
    end

    %% Build Layer
    subgraph "Build Layer"
        prebuild["prebuild.sh"]:::process
        mdbook["mdBook Core"]:::process
        plugin["plugin/mdbook-metadata/"]:::module
        main_rs["plugin/mdbook-metadata/src/main.rs"]:::module
        cargo_toml["plugin/mdbook-metadata/Cargo.toml"]:::module
        cargo_lock["plugin/mdbook-metadata/Cargo.lock"]:::module
        theme["theme/"]:::module
        book["book/ (Static Output)"]:::data
        serve["serve.sh"]:::process
    end

    %% CI/CD Layer
    subgraph "CI/CD Layer"
        workflows_dir[".github/workflows/"]:::ci
        md_lint[".github/workflows/md-lint.yaml"]:::ci
        spell_check[".github/workflows/spell-check.yml"]:::ci
    end

    %% Deployment Layer
    subgraph "Deployment Layer"
        vercel["Vercel Platform"]:::deployment
        domain["frameworks.securityalliance.org"]:::deployment
    end

    %% Collaboration/GitHub
    subgraph "Collaboration"
        repo["GitHub Repository"]:::database
        forks["Fork & PR Workflow"]:::external
        templates_dir[".github/ISSUE_TEMPLATE/"]:::database
        content_req[".github/ISSUE_TEMPLATE/content-request.md"]:::database
        update_req[".github/ISSUE_TEMPLATE/update-request.md"]:::database
        pr_template[".github/PULL_REQUEST_TEMPLATE.md"]:::database
        wordlist["wordlist.txt"]:::database
    end

    %% Local Preview
    repo -->|"clone"| serve
    serve -->|"serves site"| localhost["localhost:3000"]:::external

    %% CI/CD Flow
    repo -->|"push/PR triggers"| workflows_dir
    workflows_dir --> md_lint
    workflows_dir --> spell_check
    md_lint --> prebuild
    spell_check --> prebuild

    %% Build Pipeline
    prebuild --> mdbook
    mdbook --> plugin
    plugin --> main_rs
    plugin --> cargo_toml
    plugin --> cargo_lock
    mdbook --> theme
    mdbook --> book
    book --> vercel
    vercel --> domain

    %% Repo Content Flow
    repo --> src
    repo --> summary
    repo --> readme
    repo --> booktoml

    %% Collaboration Flow
    repo --> forks
    repo --> templates_dir
    templates_dir --> content_req
    templates_dir --> update_req
    repo --> pr_template
    repo --> wordlist

    %% Click Events
    click src "https://github.com/security-alliance/frameworks/tree/develop/src/"
    click summary "https://github.com/security-alliance/frameworks/blob/develop/src/SUMMARY.md"
    click readme "https://github.com/security-alliance/frameworks/blob/develop/src/README.md"
    click booktoml "https://github.com/security-alliance/frameworks/blob/develop/book.toml"
    click prebuild "https://github.com/security-alliance/frameworks/blob/develop/prebuild.sh"
    click serve "https://github.com/security-alliance/frameworks/blob/develop/serve.sh"
    click plugin "https://github.com/security-alliance/frameworks/tree/develop/plugin/mdbook-metadata/"
    click main_rs "https://github.com/security-alliance/frameworks/blob/develop/plugin/mdbook-metadata/src/main.rs"
    click cargo_toml "https://github.com/security-alliance/frameworks/blob/develop/plugin/mdbook-metadata/Cargo.toml"
    click cargo_lock "https://github.com/security-alliance/frameworks/blob/develop/plugin/mdbook-metadata/Cargo.lock"
    click theme "https://github.com/security-alliance/frameworks/tree/develop/theme/"
    click workflows_dir "https://github.com/security-alliance/frameworks/tree/develop/.github/workflows/"
    click md_lint "https://github.com/security-alliance/frameworks/blob/develop/.github/workflows/md-lint.yaml"
    click spell_check "https://github.com/security-alliance/frameworks/blob/develop/.github/workflows/spell-check.yml"
    click content_req "https://github.com/security-alliance/frameworks/blob/develop/.github/ISSUE_TEMPLATE/content-request.md"
    click update_req "https://github.com/security-alliance/frameworks/blob/develop/.github/ISSUE_TEMPLATE/update-request.md"
    click pr_template "https://github.com/security-alliance/frameworks/blob/develop/.github/PULL_REQUEST_TEMPLATE.md"
    click wordlist "https://github.com/security-alliance/frameworks/blob/develop/wordlist.txt"

    %% Styles
    classDef content fill:#D6E9FE,stroke:#4A90E2,color:#000
    classDef process fill:#E2F7D4,stroke:#3C763D,color:#000
    classDef module fill:#F5F5B5,stroke:#8A6D3B,color:#000
    classDef ci fill:#FCF8E3,stroke:#8A6D3B,color:#000
    classDef deployment fill:#FDEBD0,stroke:#D35400,color:#000
    classDef database fill:#ECECEC,stroke:#666,color:#000
    classDef external fill:#F0F0F0,stroke:#999,color:#000
```
