# lolbas-project/lolbas architecture

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

- Interactive diagram: https://gitdiagram.com/lolbas-project/lolbas
- Repository: https://github.com/lolbas-project/lolbas

## Overview

##### Project type and purpose
- This is a data‐driven, static content repository. Its sole purpose is to host and maintain the YAML definitions (LOLBins, LOLScripts, LOLLibs) that power a fancy public frontend (https://lolbas-project.github.io). It is not a “traditional” full-stack app with a runtime backend. Instead, it is essentially:
- A GitHub repo of source data (YML files)
- A CI/CD pipeline (GitHub Actions) that validates and publishes those files as a static site via GitHub Pages

##### File structure
- Top‐level:
- .github/workflows/ → CI workflows: yaml‐linting.yml (validates every YML), gh-pages.yml (build/deploy to GitHub Pages)
- YML‐Schema.yml & YML‐Template.yml → Schema & sample template for each entry
- yml/… → All the categorized data files that document each binary/script/library
- README.md, CONTRIBUTING.md, LICENSE, NOTICE.md, Backlog.txt → Documentation & governance
- No backend code or “src” folder—this is purely content + CI config.

##### README for additional insights
- The README confirms the goal: “document every binary, script, and library…used for Living Off The Land techniques.”
- It calls out two major technical “runtime” components:
a) The CI pipelines that lint and publish the content
b) The static site (hosted on GitHub Pages) that consumes the YML

##### Main components and relationships
A. Actors
1. Contributor (local machine)
2. End-user (browser)
B. Data Source
- yml/ directory (hundreds of .yml files)
- YML‐Schema.yml & YML‐Template.yml
C. CI/CD
1. GitHub Actions – YAML Linting workflow
2. GitHub Actions – GH Pages deployment workflow
D. Hosting & Delivery
- gh-pages branch (or /docs)
- GitHub Pages serving static HTML/CSS/JS
E. (Optional external) Frontend code
– The “fancy frontend” may be part of this repo’s Pages site (using Jekyll/JavaScript) or a separate project that pulls from these YML files

1. Contributor commits new/updated YML → pushes to origin/master
2. GitHub Actions “yaml-linting.yml” triggers → runs schema validation & lint rules
- On failure: PR is blocked, errors reported
- On success: proceeds
3. GitHub Actions “gh-pages.yml” triggers → builds static site (Jekyll, Eleventy, or custom script consuming the yml/) → pushes output to gh-pages branch
4. GitHub Pages detects gh-pages branch → serves the site at https://lolbas-project.github.io
5. End-users browse the site → dynamic client-side code reads pre-built JSON/HTML pages generated from the yml files

##### Architectural patterns & design principles
- Data-as-code: Every piece of content is plain YAML, versioned in Git
- CI/CD pipeline: Lint → Build → Deploy
- Static Site Generation: No dynamic backend at runtime, only client-side or Jekyll processing
- Schema‐driven: YML‐Schema.yml enforces consistency across hundreds of entries

##### Relevant technologies/frameworks/libraries
- Git, GitHub
- GitHub Actions (YAML linting, Pages deploy)
- YAML schema validation (JSON Schema or custom linter)
- GitHub Pages (Jekyll or static HTML/JS)
- Browser (client-side JS to enhance navigation/search)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Actors
  Contributor["Contributor"]:::actor
  EndUser["End-User"]:::actor

  %% Repository Layer
  subgraph "GitHub Repository"
    direction TB
    YMLDir[(YAML Content Store)]:::data
    subgraph "Content Directories"
      direction TB
      OSBinaries[(OSBinaries)]:::data
      OSLibraries[(OSLibraries)]:::data
      OSScripts[(OSScripts)]:::data
      OtherMSBinaries[(OtherMSBinaries)]:::data
      HonorableMentions[(HonorableMentions)]:::data
    end
    Schema[(YML-Schema.yml)]:::data
    Template[(YML-Template.yml)]:::data
    Docs[(Documentation & Governance)]:::data
  end

  %% CI/CD Layer
  subgraph "GitHub Actions"
    direction TB
    Lint["YAML Linting Workflow"]:::ci
    Deploy["Static Site Build & Deploy"]:::ci
  end

  %% Hosting Layer
  PagesBranch["gh-pages Branch"]:::hosting
  PagesHost["GitHub Pages"]:::hosting

  %% Flows
  Contributor -->|"git push"| YMLDir
  YMLDir -->|"included in"| Lint
  Schema -->|"used by"| Lint
  Template -->|"used by"| Lint
  Docs -->|"inform"| Lint
  Lint -->|"on success"| Deploy
  Deploy -->|"push to"| PagesBranch
  PagesBranch -->|"serves site at"| PagesHost
  PagesHost -->|"browses site"| EndUser

  %% Click Events
  click OSBinaries "https://github.com/lolbas-project/lolbas/tree/master/yml/OSBinaries/"
  click OSLibraries "https://github.com/lolbas-project/lolbas/tree/master/yml/OSLibraries/"
  click OSScripts "https://github.com/lolbas-project/lolbas/tree/master/yml/OSScripts/"
  click OtherMSBinaries "https://github.com/lolbas-project/lolbas/tree/master/yml/OtherMSBinaries/"
  click HonorableMentions "https://github.com/lolbas-project/lolbas/tree/master/yml/HonorableMentions/"
  click YMLDir "https://github.com/lolbas-project/lolbas/tree/master/yml/"
  click Schema "https://github.com/lolbas-project/lolbas/blob/master/YML-Schema.yml"
  click Template "https://github.com/lolbas-project/lolbas/blob/master/YML-Template.yml"
  click Lint "https://github.com/lolbas-project/lolbas/blob/master/.github/workflows/yaml-linting.yml"
  click Deploy "https://github.com/lolbas-project/lolbas/blob/master/.github/workflows/gh-pages.yml"
  click Docs "https://github.com/lolbas-project/lolbas/blob/master/README.md"
  click Docs "https://github.com/lolbas-project/lolbas/blob/master/CONTRIBUTING.md"
  click Docs "https://github.com/lolbas-project/lolbas/tree/master/LICENSE"
  click Docs "https://github.com/lolbas-project/lolbas/blob/master/NOTICE.md"
  click Docs "https://github.com/lolbas-project/lolbas/blob/master/Backlog.txt"

  %% Styles
  classDef actor fill:#dddddd,stroke:#333333,color:#000000;
  classDef data fill:#cce5ff,stroke:#003366,color:#003366;
  classDef ci fill:#d4edda,stroke:#155724,color:#155724;
  classDef hosting fill:#fff3cd,stroke:#856404,color:#856404;
```
