# beaurancourt/sovereign architecture

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

- Interactive diagram: https://gitdiagram.com/beaurancourt/sovereign
- Repository: https://github.com/beaurancourt/sovereign

## Overview

##### Main Components
- Content Files: These include Markdown files such as arcane-traditions.md, character-creation.md, classes.md, combat.md, etc. They hold the narrative and informational content for the site.
- Data Sources: The _data directory contains JSON files (e.g., feats.json, monsters.json, rules.json) that provide structured game data used to populate the site.
- Layouts & Includes: The _layouts and _includes directories house HTML template files (for instance, default.html and chapter-toc.html) that define the overall structure and reusable elements of the site.
- Assets: The assets folder (subdivided into css, js, and images) manages the site’s styling, interactivity (through JavaScript files like search.js, monster-search.js, sidebar.js), and visual assets.
- Jekyll Engine: The Jekyll build system itself (invoked via the command line) processes all of the above components through Ruby-based templating and the Liquid engine to output a fully rendered static website.
- Build Tools & Configuration: Files like Gemfile, Gemfile.lock, and build-toc.rb are used by Bundler and Jekyll to manage dependencies, build scripts, and site generation.

##### Relationships and Interactions
- Content Flow: Markdown files and JSON data feed into the Jekyll engine.
- Templating: Jekyll uses _layouts and _includes to wrap Markdown content into complete HTML pages.
- Assets Integration: The final HTML pages incorporate styles and scripts found in the assets folder for proper presentation and dynamic functionalities.
- Build Process: The build-toc.rb script and configuration files assist with generating navigational elements such as table of contents, ensuring an organized structure throughout the site.

##### Key Architectural Patterns and Design Principles
- Separation of Concerns: Content, structure, and styling are segregated into distinct directories (content in Markdown, templates in _layouts/_includes, and presentation via assets).
- Data-Driven Rendering: The _data folder is leveraged to manage structured data (game rules, stats, etc.) that can be reused across different pages.
- Static Site Generation: The project follows the static site paradigm where the build process produces pure HTML/CSS/JS outputs rather than relying on runtime server-side rendering.

##### Relevant Technologies and Libraries
- Jekyll (for static-site generation)
- Ruby (as the programming language for Jekyll and associated scripts)
- Bundler (to manage Ruby Gem dependencies)
- Liquid Templates (for embedding dynamic data into static pages)

##### Elements
- Clear Labels: For each main component – Content Files, Data Files, Layouts, Includes, Assets, Build Scripts, and the Jekyll Engine.

##### Additional Details
- Role of the Gemfile and Bundler in setting up the environment.
- Build process (jekyll serve) that continuously compiles changes into the static site.
- Optionally, note how additional scripts (like build-toc.rb) assist with dynamic content generation such as navigation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Input Nodes
    CF["Content Files"]:::content
    DS["Data Sources"]:::data
    LI["Layouts & Includes"]:::template
    BTC["Build Tools & Configuration"]:::build

    %% Processing Node
    JE["Jekyll Engine"]:::engine

    %% Assets subgraph
    subgraph "Assets"
        CSS["CSS"]:::assets
        JS["JS"]:::assets
        IMG["Images"]:::assets
    end

    %% Output Node
    GS["Generated Static Site"]:::output

    %% Connections
    CF -->|"content-flow"| JE
    DS -->|"data-flow"| JE
    LI -->|"templating"| JE
    BTC -->|"build-tools"| JE
    JE -->|"output"| GS
    CSS -->|"assets"| GS
    JS -->|"assets"| GS
    IMG -->|"assets"| GS

    %% Click Events
    click CF "https://github.com/beaurancourt/sovereign/blob/main/index.md"
    click DS "https://github.com/beaurancourt/sovereign/tree/main/_data"
    click LI "https://github.com/beaurancourt/sovereign/blob/main/_layouts/default.html"
    click CSS "https://github.com/beaurancourt/sovereign/blob/main/assets/css/custom.css"
    click JS "https://github.com/beaurancourt/sovereign/blob/main/assets/js/search.js"
    click IMG "https://github.com/beaurancourt/sovereign/tree/main/assets/images/"
    click BTC "https://github.com/beaurancourt/sovereign/blob/main/build-toc.rb"

    %% Styles
    classDef content fill:#a2d2ff,stroke:#333,stroke-width:2px;
    classDef data fill:#d4f8e8,stroke:#333,stroke-width:2px;
    classDef template fill:#ffedeb,stroke:#333,stroke-width:2px;
    classDef assets fill:#ffcad4,stroke:#333,stroke-width:2px;
    classDef engine fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef build fill:#ffe5d9,stroke:#333,stroke-width:2px;
    classDef output fill:#d0e1f9,stroke:#333,stroke-width:2px;
```
