# joelouthan/theologicus architecture

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

- Interactive diagram: https://gitdiagram.com/joelouthan/theologicus
- Repository: https://github.com/joelouthan/theologicus

## Overview

##### Main components
- Content Repository: Represented by the “src” directory, it holds all Markdown files for multiple books, sermons, confessions, and biblical texts. Also include ancillary content such as notes and bibliographies.
- Build & Static Site Generator: The project relies on mdBook (and its associated “mdbook-toc” tool in the “bin” folder) to process the Markdown content into a navigable website.
- Theming & Presentation Layer: The “theme” directory holds Handlebars templates (e.g., head.hbs, index.hbs), CSS files (including Chrome, print, and general CSS), fonts, and any JavaScript needed for interactivity.
- Configuration & Metadata: Files like book.toml (for mdBook configuration) and various .json/.toml files that inform the build process.
- Deployment Pipeline: The “netlify” folder (with edge functions) indicates how the site is deployed and served by Netlify. Also include version control (.gitignore, .gitmodules) among the infrastructure components.
- Utilities & Editor Support: Additional folders (.vscode, code-workspace files) support developer experience.

##### Relationships and interactions
- The Content Repository (Markdown files in “src”) is fed into the Static Site Generator (mdBook) that reads the configuration from book.toml.
- The Static Site Generator uses the theming assets (from the “theme” folder) to apply a consistent look and feel to the generated pages.
- The build process may also invoke utility tools (like the custom “mdbook-toc” from the “bin” folder) to generate or update tables of contents.
- Once the site is built, it is deployed via the Netlify pipeline (with custom edge functions for dynamic behaviors) that serves the final HTML/CSS/JS to end users.
- Version control and workspace files (.git, .vscode, .code-workspace files) are used during development to manage and maintain the content and build scripts.

##### Important architectural patterns and design principles
- Separation of Concerns: Notice how the project splits content (Markdown files) from presentation (theme files) and build configuration (book.toml and supporting scripts).
- Static Site Generation: The use of a tool like mdBook underscores a pattern where content is pre-rendered into static pages that can be hosted on a CDN (via Netlify).
- Modularity and Extensibility: With multiple submodules (evident from the .gitmodules file and versioned releases) and external deploy pipelines, the design anticipates changes and integrations (like a Swift port or submodules for 1689).
- Configuration-driven builds: The presence of several configuration files (e.g., for the Markdown linter and workspace settings) indicates an emphasis on automation and standardization in the build and deployment process.

##### Relevant technologies, frameworks, and libraries
- mdBook and mdbook-toc for static site generation.
- Markdown as the primary content language.
- Handlebars (indicated by .hbs files in the theme) for templating.
- CSS and JavaScript (including custom “book.js”) for styling and interactivity.
- Netlify for deployment and custom edge functions (JavaScript files such as “blockUserAgent.js” and “hello.js”).
- Auxiliary tools (VSCode for development, Git for version control, and possibly Rust given mdBook’s Rust ecosystem).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Content Source
    subgraph "Content Source"
        CR("Content Repository (src)")
    end

    %% Configuration & Metadata
    subgraph "Configuration & Metadata"
        Config("Build Config (book.toml)")
        Lint(".markdownlint.json")
    end

    %% Build Process
    subgraph "Build Process"
        Builder("Static Site Generator (mdBook)")
        TOC("mdbook-toc (TOC Tool)")
    end

    %% Theme & Presentation
    subgraph "Theme & Presentation"
        Head("Template: head.hbs")
        Index("Template: index.hbs")
        CSS("CSS Files")
        BookJS("book.js")
    end

    %% Deployment Pipeline
    subgraph "Deployment Pipeline"
        Netlify("Netlify Deployment (netlify)")
        Edge("Edge Functions")
        Website("Final Website (HTML/CSS/JS)")
    end

    %% Developer Tools
    subgraph "Developer Tools"
        VSCode("VSCode (.vscode)")
        Workspace("Workspace Config (theologicus.code-workspace)")
    end

    %% Relationships
    CR -->|"feeds"| Builder
    Config -->|"configures"| Builder
    Lint -->|"enforces"| Builder

    Head -->|"applies"| Builder
    Index -->|"applies"| Builder
    CSS -->|"applies"| Builder
    BookJS -->|"applies"| Builder

    Builder -->|"callsTOC"| TOC
    Builder -->|"buildsSite"| Netlify
    Netlify -->|"includes"| Edge
    Edge -->|"serves"| Website

    VSCode -->|"supports"| CR
    VSCode -->|"supports"| Builder
    Workspace -->|"supports"| CR
    Workspace -->|"supports"| Builder

    %% Click Events
    click CR "https://github.com/joelouthan/theologicus/tree/main/src/"
    click Config "https://github.com/joelouthan/theologicus/blob/main/book.toml"
    click Lint "https://github.com/joelouthan/theologicus/blob/main/.markdownlint.json"
    click TOC "https://github.com/joelouthan/theologicus/tree/main/bin/bin/mdbook-toc"
    click Head "https://github.com/joelouthan/theologicus/blob/main/theme/head.hbs"
    click Index "https://github.com/joelouthan/theologicus/blob/main/theme/index.hbs"
    click CSS "https://github.com/joelouthan/theologicus/tree/main/theme/css/"
    click BookJS "https://github.com/joelouthan/theologicus/blob/main/theme/book.js"
    click Netlify "https://github.com/joelouthan/theologicus/tree/main/netlify/"
    click Edge "https://github.com/joelouthan/theologicus/tree/main/netlify/edge-functions/"
    click VSCode "https://github.com/joelouthan/theologicus/tree/main/.vscode/"
    click Workspace "https://github.com/joelouthan/theologicus/blob/main/theologicus.code-workspace"

    %% Styles
    classDef content fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef build fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef theme fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
    classDef deploy fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef dev fill:#FAD7A0,stroke:#884EA0,stroke-width:2px;
    
    class CR content;
    class Config,Lint config;
    class Builder,TOC build;
    class Head,Index,CSS,BookJS theme;
    class Netlify,Edge,Website deploy;
    class VSCode,Workspace dev;
```
