# colinwilson/lotusdocs architecture

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

- Interactive diagram: https://gitdiagram.com/colinwilson/lotusdocs
- Repository: https://github.com/colinwilson/lotusdocs

## Overview

##### Project Type and Purpose
- Project type: A Hugo-based static documentation theme
- Purpose: Provide a customizable, SEO-friendly, multi-lingual docs site theme that users can integrate into their Hugo projects

##### File Structure
- Top-level directories:
– archetypes/ (default front-matter templates)
– assets/ (SCSS, JS, images for theme styling and docs site)
– data/ (YAML data files used by templates)
– exampleSite/ (an example Hugo site using the theme)
– i18n/ (translation files)
– layouts/ (theme’s HTML templates and shortcodes)
- Configuration files: config.toml, netlify.toml, theme.toml
- CI workflow: .github/workflows/codeql-analysis.yaml

##### Extract Architectural Insights from README
- The theme is a Hugo Module, importing:
– “colinwilson/lotusdocs” (this repo)
– “gohugoio/hugo-mod-bootstrap-scss” (Bootstrap SCSS module)

##### Main Components to Model
A. Content Layer
– Markdown files in content/ (inside exampleSite)
– Data files (landing.yaml)
– i18n translation bundles
– Archetypes (default front-matter templates)
B. Theme Code (Lotus Docs module)
– layouts/ (page templates, partials, shortcodes)
– assets/ (SCSS → CSS pipeline, JS bundles, images)
– config.toml & theme.toml (default theme parameters)
C. External Modules & Libraries
– Hugo Bootstrap SCSS Module
D. Build Engine
– Hugo (Extended)
– Hugo Modules system (module imports, replacements)
E. CI/CD Pipeline
– GitHub Actions for code scanning (CodeQL)
– netlify.toml (deploy configuration)
– Potential deployment targets: GitHub Pages, Netlify, Vercel, Cloudflare Pages
F. Runtime / Hosting Layer
– Static assets (HTML, CSS, JS, images, fonts) served from CDN / SSG host
– Client‐side: Syntax highlighting, dark mode toggle, search index

##### Relationships & Data Flows
- Author writes Markdown + updates data/i18n →
Hugo (build) loads theme code + external modules →
Processes SCSS, JS, templates →
Outputs static site artifacts →
CI/CD pushes artifacts to host →
End-users’ browsers fetch static assets and run client-side JS plugins

##### Architectural Patterns & Design Principles
- Static-site generator pattern
- Module composition (Hugo Modules)
- Separation of concerns: content vs. presentation vs. build logic
- Plugin-based extensibility (shortcodes, SCSS partials, JS bundles)

##### Capturing Essential Details
- Don’t omit:
– Archetypes (front-matter templates)
– data/ and i18n/ as inputs to layouts
– exampleSite/ as a live demo consumer
– The role of SCSS and JS under assets/ and assets/docs/
- That the output is purely static; client runs JS plugins for search, syntax highlighting, dark mode, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        direction TB
        MD["Markdown Files\n(exampleSite/content/)"]:::source
        DATA["Data Files\n(data/landing.yaml)"]:::source
        I18N["i18n Bundles\n(i18n/)"]:::source
        ARCH["Archetypes\n(archetypes/)"]:::source
    end

    %% Theme Code
    subgraph "Theme Code"
        direction TB
        LAYOUTS["Layouts & Shortcodes\n(layouts/)"]:::source
        ASSETS["Assets (SCSS, JS, Images)\n(assets/)"]:::source
        THEMETOML["Theme Defaults\n(theme.toml)"]:::source
        CONFIG["User Config Example\n(config.toml)"]:::source
    end

    %% External Modules & Libraries
    subgraph "External Modules & Libraries"
        direction TB
        GOMOD["Hugo Module Definitions\n(go.mod)"]:::source
        PRISM["Prism.js"]:::external
        FLEX["FlexSearch"]:::external
        KATEX["KaTeX"]:::external
        MERMAID["Mermaid"]:::external
        DOCS["DocSearch"]:::external
        GFONTS["Google Fonts"]:::external
        MICONS["Material Icons"]:::external
        BS["Bootstrap SCSS Module"]:::external
    end

    %% Build Engine
    subgraph "Build Pipeline"
        direction TB
        HUGO["Hugo Build (Extended)"]:::process
        SCSS["SCSS → CSS Compiler"]:::process
        JSBUNDLE["JS Bundler"]:::process
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CODEQL["CodeQL Analysis\n(.github/workflows/codeql-analysis.yaml)"]:::process
        NETLIFYCFG["Netlify Deploy Config\n(netlify.toml)"]:::process
    end

    %% Hosting/Runtime Layer
    subgraph "Hosting & Runtime"
        direction TB
        STATIC["Static Site Assets\n(static/)"]:::runtime
        TARGETS["Deployment Targets\n(GitHub Pages, Netlify, Vercel, Cloudflare)"]:::runtime
        CLIENT["End-User Browser\n(Client-side JS Plugins)"]:::runtime
    end

    %% Connections
    MD -->|provides content| HUGO
    DATA -->|provides data| HUGO
    I18N -->|provides translations| HUGO
    ARCH -->|provides templates| HUGO

    LAYOUTS -->|templates| HUGO
    ASSETS -->|SCSS & JS assets| HUGO
    THEMETOML -->|default params| HUGO
    CONFIG -->|example config| HUGO

    GOMOD -->|module imports| HUGO
    BS -->|hugo mod import| HUGO
    PRISM -->|runtime lib| CLIENT
    FLEX -->|runtime lib| CLIENT
    KATEX -->|runtime lib| CLIENT
    MERMAID -->|runtime lib| CLIENT
    DOCS -->|runtime lib| CLIENT
    GFONTS -->|runtime service| CLIENT
    MICONS -->|runtime service| CLIENT

    HUGO -->|runs SCSS compile| SCSS
    HUGO -->|runs JS bundle| JSBUNDLE
    SCSS -->|compiles to CSS| STATIC
    JSBUNDLE -->|bundles JS| STATIC
    HUGO -->|outputs static HTML| STATIC

    STATIC -->|deployed via| TARGETS
    TARGETS -->|fetched by| CLIENT

    CODEQL -->|scans code| GOMOD
    NETLIFYCFG -->|configures deploy| TARGETS

    %% Click Events
    click MD "https://github.com/colinwilson/lotusdocs/tree/release/exampleSite/content/"
    click DATA "https://github.com/colinwilson/lotusdocs/blob/release/data/landing.yaml"
    click I18N "https://github.com/colinwilson/lotusdocs/tree/release/i18n/"
    click ARCH "https://github.com/colinwilson/lotusdocs/tree/release/archetypes/"
    click LAYOUTS "https://github.com/colinwilson/lotusdocs/tree/release/layouts/"
    click ASSETS "https://github.com/colinwilson/lotusdocs/tree/release/assets/"
    click THEMETOML "https://github.com/colinwilson/lotusdocs/blob/release/theme.toml"
    click CONFIG "https://github.com/colinwilson/lotusdocs/blob/release/config.toml"
    click GOMOD "https://github.com/colinwilson/lotusdocs/blob/release/go.mod"
    click CODEQL "https://github.com/colinwilson/lotusdocs/blob/release/.github/workflows/codeql-analysis.yaml"
    click NETLIFYCFG "https://github.com/colinwilson/lotusdocs/blob/release/netlify.toml"
    click STATIC "https://github.com/colinwilson/lotusdocs/tree/release/static/"

    %% Styles
    classDef source fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef process fill:#D8FDD8,stroke:#28a745,color:#28a745;
    classDef external fill:#FFF4E5,stroke:#ff7f0e,color:#ff7f0e;
    classDef runtime fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
