# llsoftsec/llsoftsecbook architecture

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

- Interactive diagram: https://gitdiagram.com/llsoftsec/llsoftsecbook
- Repository: https://github.com/llsoftsec/llsoftsecbook

## Overview

##### Main Components
- Content Sources:
- The core book content is contained within files like book.md and its associated bibliography file (book.bib).
- Supporting media (e.g., images) reside in the img folder.
- Theme & Styling:
- The “theme” directory holds templates and styles for different output formats: subdirectories for HTML (with various Lua filters and CSS files), EPUB (with custom CSS), and TeX (for PDF generation via pandoc_template.tex).
- Build & Processing Infrastructure:
- Build scripts: Makefile (which calls “make all”) and build_with_docker.sh/.bat that ensure builds run in a controlled Docker container environment.
- Docker: The docker folder includes a Dockerfile and entrypoint.sh which define the containerized environment to install specific versions of Pandoc, LaTeX, and required packages.
- The .mlc_config.json and other configuration files help control build parameters.
- Continuous Integration / Version Control:
- The .github/workflows folder contains CI/CD scripts (e.g., main.yml) that likely automate the build process, test contributions, and help publish outputs (e.g., via GitHub pages).
- Files like .gitignore, CODE_OF_CONDUCT.md, LICENSE, and contributing.md indicate robust community and collaboration practices.

##### Establishing Relationships and Workflows
- Source-to-Build Flow:
- The main markdown content (book.md) and its supporting bibliography (book.bib) along with images are processed using pandoc and LaTeX. This processing relies on styling templates provided in the theme folder.
- Build Orchestration:
- The Makefile serves as the orchestrator for the book build, invoking either local or Dockerized builds.
- The Docker container (configured via docker/Dockerfile and entrypoint.sh) encapsulates the required environment to guarantee consistent builds.
- Deployment and Automation:
- GitHub workflows kick off builds on code changes or pull requests, ensuring that the outputs (HTML, PDF) are up-to-date and testing the integrity of the build process.

##### Technologies and Tools
- Pandoc – used for converting markdown to various formats.
- LaTeX – integrated when generating the PDF version.
- Docker – for containerizing the build environment.
- GitHub Actions – for continuous integration and automated builds.
- Make – for build orchestration.

##### Detail
- Relationship between the configuration (like .mlc_config.json and Makefile directives) and the build pipeline.
- That the automation via GitHub workflows ensures ongoing integration with contributions from the community.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CI/CD & Version Control
    subgraph "CI/CD & Version Control"
        CI1("GitHub Workflows"):::ci
        CI2(".gitignore"):::ci
        CI3("CODE_OF_CONDUCT.md"):::ci
        CI4("LICENSE"):::ci
        CI5("contributing.md"):::ci
    end

    %% Content Sources
    subgraph "Content Sources"
        CS1("book.md"):::content
        CS2("book.bib"):::content
        CS3("Images (img)"):::content
    end

    %% Theme & Styling Assets
    subgraph "Theme & Styling Assets"
        T1("HTML Templates"):::theme
        T2("EPUB Templates"):::theme
        T3("TeX Template"):::theme
    end

    %% Build Tools & Scripts and Configuration
    subgraph "Build Tools & Scripts"
        B1("Makefile"):::build
        B2("build_with_docker.sh"):::build
        B3("build_with_docker.bat"):::build
        BC(".mlc_config.json"):::config
    end

    %% Docker Environment
    subgraph "Docker Environment"
        D1("Dockerfile"):::docker
        D2("Entrypoint (entrypoint.sh)"):::docker
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        O1("PDF (book.pdf)"):::output
        O2("HTML (book.html)"):::output
    end

    %% Relationships
    CS1 -->|"feeds"| B1
    CS2 -->|"feeds"| B1
    CS3 -->|"feeds"| B1

    T1 -->|"applied"| B1
    T2 -->|"applied"| B1
    T3 -->|"applied"| B1

    BC -->|"configures"| B1

    CI1 -->|"triggers"| B1

    B1 -->|"builds in"| D1
    B2 -->|"auxiliary"| D1
    B3 -->|"auxiliary"| D1

    D1 -->|"generates"| O1
    D1 -->|"generates"| O2

    %% Click Events for Content Sources
    click CS1 "https://github.com/llsoftsec/llsoftsecbook/blob/main/book.md"
    click CS2 "https://github.com/llsoftsec/llsoftsecbook/blob/main/book.bib"
    click CS3 "https://github.com/llsoftsec/llsoftsecbook/tree/main/img/"

    %% Click Events for Theme & Styling Assets
    click T1 "https://github.com/llsoftsec/llsoftsecbook/tree/main/theme/html/"
    click T2 "https://github.com/llsoftsec/llsoftsecbook/tree/main/theme/epub/"
    click T3 "https://github.com/llsoftsec/llsoftsecbook/tree/main/theme/tex/"

    %% Click Events for Build Tools & Scripts and Configuration
    click B1 "https://github.com/llsoftsec/llsoftsecbook/tree/main/Makefile"
    click B2 "https://github.com/llsoftsec/llsoftsecbook/blob/main/build_with_docker.sh"
    click B3 "https://github.com/llsoftsec/llsoftsecbook/blob/main/build_with_docker.bat"
    click BC "https://github.com/llsoftsec/llsoftsecbook/blob/main/.mlc_config.json"

    %% Click Events for Docker Environment
    click D1 "https://github.com/llsoftsec/llsoftsecbook/tree/main/docker/Dockerfile"
    click D2 "https://github.com/llsoftsec/llsoftsecbook/blob/main/docker/entrypoint.sh"

    %% Click Events for CI/CD & Version Control
    click CI1 "https://github.com/llsoftsec/llsoftsecbook/tree/main/.github/workflows/"
    click CI2 "https://github.com/llsoftsec/llsoftsecbook/blob/main/.gitignore"
    click CI3 "https://github.com/llsoftsec/llsoftsecbook/blob/main/CODE_OF_CONDUCT.md"
    click CI4 "https://github.com/llsoftsec/llsoftsecbook/tree/main/LICENSE"
    click CI5 "https://github.com/llsoftsec/llsoftsecbook/blob/main/contributing.md"

    %% Styles
    classDef content fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef theme fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef build fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#FA8072,stroke:#000,stroke-width:2px;
    classDef docker fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef ci fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef output fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
