# leandropa/natile architecture

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

- Interactive diagram: https://gitdiagram.com/leandropa/natile
- Repository: https://github.com/leandropa/natile

## Overview

##### Project type and purpose
- This is an open-source, Ruby-based static site generator that produces a fully customized LinkTree-style page and deploys it on GitHub Pages.
- It reads a YAML config, loads plugins to fetch dynamic values (e.g., Medium followers, GitHub stars), applies a theme, and emits a static site.

##### File structure
- Top-level files:
- Gemfile/Gemfile.lock – Ruby dependencies for the generator
- scaffold.rb – the generator’s entry point
- config.yml – site configuration and plugin settings
- Makefile & deploy.sh – local build/deploy helpers
- .github/workflows/build.yml – CI/CD pipeline for automatic builds
- Directories:
- plugins/ – plugin classes implementing a common interface (Plugin.rb)
- themes/ – each theme has HTML template, CSS, JS, and assets
- _output/ – auto-generated static output (do not edit)

##### README insights
- Confirms features: plugin extensibility, theme swapping, GitHub Actions–driven automatic redeployment, GitHub Pages hosting.
- Shows how config.yml drives everything, and how plugins inject dynamic data.

##### Main components and interactions
a. Components
- Developer/Repository – user pushes code and config to GitHub repo
- CI/CD (GitHub Actions runner) – triggers on schedule or push
- Generator Engine (scaffold.rb + plugins)
- Plugins – fetch external data from:
– GitHub API
– Medium API
- Config (config.yml) – supplies theme choice, site data, plugin settings
- Themes/templates – HTML, CSS, JS assets under themes/default (or custom theme)
- Output (_output) – generated static pages
- Hosting (GitHub Pages) – serves the gh-pages branch (static site)
- End Users – browse the live site

b. Relationships & data flows
1. GitHub Push or Scheduled Trigger → GitHub Actions
2. Actions Runner
- Checks out code
- Installs Ruby gems (Gemfile)
- Runs scaffold.rb
3. scaffold.rb
- Loads config.yml → passes settings to generator
- Loads each plugin (plugins/*.rb) → each plugin calls its external API → returns dynamic data
- Reads theme templates (themes/<theme>/index.html, CSS, JS)
- Renders HTML pages, injecting both static config data and plugin outputs
- Writes generated files into _output/
4. Actions Runner
- Commits/switches to gh-pages branch
- Copies _output/ contents
- Pushes to remote gh-pages
5. GitHub Pages
- Detects changes on gh-pages branch → serves the static site
6. End User
- Requests the URL → GitHub Pages returns the static HTML/CSS/JS

c. Architectural patterns & design principles
- Plugin Pattern – loose coupling of dynamic-data providers via a common Plugin interface
- Template-based static site generation
- CI/CD as infrastructure – automated, scheduled or on-push builds
- Separation of concerns – configuration, data fetching, templating, and deployment are distinct

d. Key technologies/frameworks
- Ruby & Bundler (Gemfile) – runtime for scaffold script
- GitHub Actions – CI/CD and scheduled redeploys
- YAML – config format (config.yml)
- HTML/CSS/JS – theming assets under themes/
- GitHub Pages – hosting platform

##### Be detailed, but don’t over-compartmentalize
- Piece: code, config, data-fetch, template, output, CI, hosting, external API.
- How new plugins or themes plug into the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer & Repo"
        Repo["GitHub Repository"]:::code
    end

    Repo -->|"push / scheduled trigger"| ActionsRunner["GitHub Actions Runner"]:::cicd

    subgraph "CI/CD Pipeline"
        CIYaml["CI/CD Pipeline (build.yml)"]:::cicd
    end

    ActionsRunner -->|triggers| CIYaml
    CIYaml -->|"checkout & install gems"| Engine["scaffold.rb Engine"]:::code

    Engine -->|"loads config"| Config["config.yml"]:::config

    subgraph "Plugins (Dynamic Data Providers)"
        PluginInterface["Plugin Interface"]:::code
        AgePlugin["AgeCalculatorPlugin"]:::code
        StarsPlugin["GithubRepoStarsCountPlugin"]:::code
        MediumPlugin["MediumFollowersCountPlugin"]:::code
        ExternalGitHubAPI["GitHub API"]:::external
        ExternalMediumAPI["Medium API"]:::external
    end

    Engine -->|"initializes plugins via interface"| PluginInterface
    PluginInterface --> AgePlugin
    PluginInterface --> StarsPlugin
    PluginInterface --> MediumPlugin
    StarsPlugin -->|"HTTP request"| ExternalGitHubAPI
    MediumPlugin -->|"HTTP request"| ExternalMediumAPI

    subgraph "Theme Templates & Assets (themes/default)"
        HTML["index.html"]:::code
        CSS["styles.css"]:::code
        JS["scripts.js"]:::code
        FA["fontawesome/"]:::code
        IMG["images/"]:::code
    end

    Engine -->|"reads theme files"| HTML
    Engine --> CSS
    Engine --> JS
    Engine --> FA
    Engine --> IMG

    Engine -->|"renders pages"| Output["_output/"]:::output

    subgraph "Deployment Helpers"
        DeployScript["deploy.sh"]:::cicd
        MakefileNode["Makefile"]:::cicd
    end

    ActionsRunner -->|"runs deploy helpers"| DeployScript
    ActionsRunner --> MakefileNode
    DeployScript --> Output
    MakefileNode --> Output
    ActionsRunner -->|"push gh-pages branch"| GhPagesBranch["gh-pages branch"]:::code

    GhPagesBranch -->|"detected changes"| Pages["GitHub Pages"]:::hosting
    Pages -->|"serves static site"| EndUser["End Users"]:::hosting

    %% Click Events
    click Repo "https://github.com/leandropa/natile/tree/main//"
    click CIYaml "https://github.com/leandropa/natile/blob/main/.github/workflows/build.yml"
    click Engine "https://github.com/leandropa/natile/blob/main/scaffold.rb"
    click Config "https://github.com/leandropa/natile/blob/main/config.yml"
    click PluginInterface "https://github.com/leandropa/natile/blob/main/plugins/Plugin.rb"
    click AgePlugin "https://github.com/leandropa/natile/blob/main/plugins/AgeCalculatorPlugin.rb"
    click StarsPlugin "https://github.com/leandropa/natile/blob/main/plugins/GithubRepoStarsCountPlugin.rb"
    click MediumPlugin "https://github.com/leandropa/natile/blob/main/plugins/MediumFollowersCountPlugin.rb"
    click HTML "https://github.com/leandropa/natile/blob/main/themes/default/index.html"
    click CSS "https://github.com/leandropa/natile/blob/main/themes/default/styles.css"
    click JS "https://github.com/leandropa/natile/blob/main/themes/default/scripts.js"
    click FA "https://github.com/leandropa/natile/tree/main/themes/default/fontawesome/"
    click IMG "https://github.com/leandropa/natile/tree/main/themes/default/images/"
    click Output "https://github.com/leandropa/natile/tree/main/_output/"
    click DeployScript "https://github.com/leandropa/natile/blob/main/deploy.sh"
    click MakefileNode "https://github.com/leandropa/natile/tree/main/Makefile"

    %% Styles
    classDef code fill:#AED6F1,stroke:#1F618D,color:#1B2631
    classDef config fill:#A9DFBF,stroke:#229954,color:#1B2631
    classDef cicd fill:#F5B041,stroke:#D35400,color:#1B2631
    classDef hosting fill:#D2B4DE,stroke:#6C3483,color:#1B2631
    classDef external fill:#F1948A,stroke:#C0392B,color:#1B2631
    classDef output fill:#A3E4D7,stroke:#117864,color:#1B2631
```
