# calcobalt/pagefull architecture

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

- Interactive diagram: https://gitdiagram.com/calcobalt/pagefull
- Repository: https://github.com/calcobalt/pagefull

## Overview

##### Main Components
- Source Content & Configuration:
- Markdown pages and posts: Directory _posts (with Markdown files), _tabs, and index.html.
- Configuration files: _config.yml, Gemfile, and various dotfiles.
- Data files: Directory _data (with authors, locales, etc.), which feed structured information (e.g., authors, media, origins).

- Presentation & Styling:
- Layouts: Directory _layouts provides various page templates (home.html, post.html, tag layouts, etc.).
- Includes/Partials: Directory _includes contains reusable HTML snippets (analytics, embed, navigation, sidebar, etc.).
- Styles: The _sass directory holds the SCSS files, abstract files, component and layout styles, themes (dark/light), vendor styles like Bootstrap; assets/css and assets/img also support the visual aspect.

- Interactive & Client-Side Enhancements:
- JavaScript: The _javascript directory contains JS functionality split into modules for components (back-to-top, search, image handling, etc.) and PWA support (sw.js, app.js) for offline capability.
- Asset bundling: Files such as package.json, rollup.config.js, and purgecss.js indicate a build process for CSS/JS optimization.

- Build & Deployment:
- Jekyll Build Process: The Jekyll engine uses the configuration, layouts, includes, and markdown posts to generate the static site.
- Workflows/Deployment: GitHub workflows (in .github/workflows) outline CI/CD and GitHub Pages deployment.
- Dev Containers: The .devcontainer folder and related configuration support containerized development environments.

##### Relationships and Interactions
- Input and Configuration:
- The Jekyll build engine reads _config.yml, metadata from _data files, and each Markdown post’s front matter.
- Gemfile (and gemspec) define Ruby dependencies required for building the theme.
- Thematic Rendering:
- Content is processed by layouts (_layouts) using “includes” components to assemble the final HTML.
- SCSS files in _sass are compiled (likely via a build tool like Rollup and configured in package.json) to generate styling, which is then rendered by the layouts.
- Enhancements and Interactivity:
- JavaScript modules enhance behavior on the client side (e.g., search interaction, PWA service worker registration, comment system integrations).
- External services/analytics integrations are managed via specific partials in _includes (for Google Analytics, Matomo, etc.)—these are injected into site pages.
- Build and Deployment Pipeline:
- Local development is aided by dev container configurations; CI workflows (GitHub Actions) monitor commits and deploy via GitHub Pages.
- Rollup and other build scripts (tools/run.sh, tools/test.sh) orchestrate asset bundling and website optimizations.

##### Architectural Patterns and Design Principles
- Separation of Concerns: There is a clear separation between content (posts, data), presentation (layouts, includes, SCSS), and interactive behavior (JavaScript modules).
- Modularity and Extensibility: The theme is designed to be configurable (with data files, localized content, theming via separate SCSS files) and supports plugin-like integrations (e.g., different comment systems and analytics engines).
- Static Generation Pipeline: The system leverages Jekyll’s static site generation pipeline and incorporates modern build tools (Rollup, PurgeCSS for optimization, and PWA support) to improve performance and maintainability.

##### Relevant Technologies and Frameworks
- Ruby and Jekyll: The backbone for static site generation.
- SCSS/CSS: For styling with modular organization under _sass.
- JavaScript: Custom modules, PWA support (service workers), and enhancement scripts under _javascript.
- GitHub Actions and Dev Containers: For CI/CD and reproducible development environments.
- External libraries integrated via partials (e.g., analytics, comment systems, and embed providers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content & Configuration
    subgraph "Content & Configuration"
        posts["Markdown Posts (_posts)"]
        tabs["Tabs (_tabs)"]
        index["Index Page (index.html)"]
        config["Configuration (_config.yml)"]
        gemfile["Gemfile"]
        data["Data Files (_data)"]
    end

    %% Jekyll Core
    subgraph "Jekyll Core"
        jekyll["Jekyll Engine"]
    end

    %% Presentation & Styling
    subgraph "Presentation & Styling"
        layouts["Layouts (_layouts)"]
        includes["Includes/Partials (_includes)"]
        sass["SCSS Styles (_sass)"]
        css["CSS (assets/css)"]
        img["Images (assets/img)"]
    end

    %% Interactive & Client-Side Enhancements
    subgraph "Interactive & Client-Side"
        js["JavaScript Modules (_javascript)"]
        pwa["PWA (_javascript/pwa)"]
        package["Package File (package.json)"]
        rollup["Rollup Config (rollup.config.js)"]
        purgecss["PurgeCSS (purgecss.js)"]
        tools["Tools (tools)"]
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        workflows["GitHub Workflows (.github/workflows)"]
        devcontainers["Dev Containers (.devcontainer)"]
    end

    %% Final Deployed Site
    final["Deployed Site"]

    %% Data Flow Connections
    posts --> jekyll
    tabs --> jekyll
    index --> jekyll
    config --> jekyll
    gemfile --> jekyll
    data --> jekyll

    jekyll --> layouts
    jekyll --> includes
    jekyll --> sass

    layouts --> final
    includes --> final
    sass --> final
    css --> final
    img --> final

    jekyll --> js
    js --> pwa

    package --> rollup
    rollup --> purgecss
    tools --> purgecss

    js --> final
    pwa --> final
    package --> final
    rollup --> final
    purgecss --> final
    tools --> final

    final --> workflows
    workflows --> devcontainers

    %% Style Classes
    class posts,tabs,index,config,gemfile,data source;
    class layouts,includes,sass,css,img presentation;
    class js,pwa,package,rollup,purgecss,tools interactive;
    class workflows,devcontainers build;
    class jekyll engine;
    class final finalcls;

    classDef source fill:#fef2cc,stroke:#e2b007,stroke-width:2px;
    classDef presentation fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef interactive fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef build fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef engine fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef finalcls fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    %% Click Events for Component Mapping
    click posts "https://github.com/calcobalt/pagefull/tree/master/_posts"
    click tabs "https://github.com/calcobalt/pagefull/tree/master/_tabs"
    click index "https://github.com/calcobalt/pagefull/blob/master/index.html"
    click config "https://github.com/calcobalt/pagefull/blob/master/_config.yml"
    click gemfile "https://github.com/calcobalt/pagefull/tree/master/Gemfile"
    click data "https://github.com/calcobalt/pagefull/tree/master/_data"
    click layouts "https://github.com/calcobalt/pagefull/tree/master/_layouts"
    click includes "https://github.com/calcobalt/pagefull/tree/master/_includes"
    click sass "https://github.com/calcobalt/pagefull/tree/master/_sass"
    click css "https://github.com/calcobalt/pagefull/tree/master/assets/css"
    click img "https://github.com/calcobalt/pagefull/tree/master/assets/img"
    click js "https://github.com/calcobalt/pagefull/tree/master/_javascript"
    click pwa "https://github.com/calcobalt/pagefull/tree/master/_javascript/pwa"
    click package "https://github.com/calcobalt/pagefull/blob/master/package.json"
    click rollup "https://github.com/calcobalt/pagefull/blob/master/rollup.config.js"
    click purgecss "https://github.com/calcobalt/pagefull/blob/master/purgecss.js"
    click tools "https://github.com/calcobalt/pagefull/tree/master/tools"
    click workflows "https://github.com/calcobalt/pagefull/tree/master/.github/workflows"
    click devcontainers "https://github.com/calcobalt/pagefull/blob/master/.devcontainer"
```
