# ganitak/sparky architecture

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

- Interactive diagram: https://gitdiagram.com/ganitak/sparky
- Repository: https://github.com/ganitak/sparky

## Overview

##### Project type and purpose
- This is a static website built with Hugo (a Go-based Static Site Generator).
- It serves as an informational “electrician” site with multiple Markdown-driven pages, custom CSS/JS assets, and a Hugo theme (hugo-initio).
- Deployment target is Netlify; future plans include Grafana for analytics and embedded services (Calendly, Google Analytics).

##### File structure
- Top-level:
– config.toml – Hugo site configuration
– content/ – Markdown files for each page
– layouts/ – HTML templates (baseof, list, single) + partials (header, footer, analytics)
– assets/ – custom CSS and JS (styles.css, 404.css, template.js, html5shiv.js)
– static/ – static images served as-is
– themes/hugo-initio/ – upstream theme code, its own assets, layouts, exampleSite
- No backend code or database; purely frontend SSG.
- Git submodule (.gitmodules) points to the theme or other external repos.

##### Key insights from README
- Uses Hugo extended (for SCSS support via CGO_ENABLED).
- Deployed on Netlify (CI/CD pipeline: Git push → Netlify build → CDN publish).
- Integrates analytics via Google Analytics partial; plans for Grafana dashboards.
- Embeds Calendly widget for appointment scheduling.

##### Main components
a. Developer Environment
– Local machine running `hugo server` or `hugo build`
– Git CLI to commit/push code to remote repo (e.g., GitHub)
– Go toolchain & C compiler for Hugo extended
b. Source Repository
– Hugo project & theme submodule
– config.toml, content/, layouts/, assets/, static/
c. CI/CD Pipeline (Netlify)
– Netlify build step runs Hugo → produces `/public` folder
– Asset optimization, SASS compilation (if any), template rendering
d. Hosting / CDN
– Netlify CDN serves static files (HTML, CSS, JS, images) to end users
e. Browser / End User
– Loads pages, CSS, JS; executes template.js (animations, navigation)
– Runs DarkReader extension (optional)
– Triggers Google Analytics calls
– Clicks “Calendly” embed to schedule
f. External Services
– Google Analytics (via analyticstracking.html partial)
– Calendly widget (embedded via content or shortcode)
– Future Grafana dashboards (consuming site metrics)

##### Relationships & data flow
- Developer → Git repo (push) → Netlify trigger
- Netlify → Hugo build → artifacts → CDN
- Browser requests page → CDN responds with HTML/CSS/JS/images
- Page JS/media → Google Analytics endpoint
- User interacts with Calendly embed → Calendly servers
- (Future) Hugo logs or Netlify logs → Grafana for dashboards

##### Architectural patterns & design principles
- Static Site Generation – no runtime backend.
- Template-Content separation – layouts + content/
- Asset pipeline – custom CSS/JS under assets/ processed by Hugo extended.
- Submodule theming – decouples upstream theme updates from customizations.
- CI/CD – automated build and deploy via Git hooks.

– Processes (rounded rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        Local["Local Machine\nhugo server/build"]:::developer
        GitCLI["Git CLI"]:::developer
        GoTool["Go Toolchain & C Compiler"]:::developer
    end

    %% Source Repository & Theme
    subgraph "Source Repository & Theme"
        Repo["Source Repository\nJB-electricite/"]:::source
        GitSub[".gitmodules"]:::source
        Config["config.toml"]:::source
        Content["content/"]:::source
        Archetype["archetypes/default.md"]:::source
        subgraph "Layouts"
            LayoutsDefault["_default/"]:::source
            Header["header.html"]:::source
            Footer["footer.html"]:::source
            Analytics["analyticstracking.html"]:::source
        end
        Shortcode["target.html"]:::source
        subgraph "Assets"
            CSS1["styles.css"]:::source
            CSS2["404.css"]:::source
            JS1["template.js"]:::source
            JS2["html5shiv.js"]:::source
        end
        Static["static/images/"]:::source
        Theme["themes/hugo-initio/"]:::source
        Lock[".hugo_build.lock"]:::source
    end

    %% CI/CD Pipeline
    subgraph "CI/CD (Netlify)"
        NetlifyBuild["Netlify Build\n(hugo build)"]:::cicd
        Public["/public\n(Static Site)"]:::cicd
    end

    %% CDN / Hosting
    subgraph "CDN / Hosting"
        CDN["Netlify CDN"]:::cdn
    end

    %% Browser / End User
    subgraph "Browser / End User"
        Browser["Browser"]:::browser
    end

    %% External Services
    subgraph "External Services"
        GA["Google Analytics"]:::external
        Calendly["Calendly Service"]:::external
        Grafana["Grafana Dashboards"]:::external
    end

    %% Connections
    Local -->|"git push"| Repo
    GitCLI -->|"push code"| Repo
    GoTool -->|build support| Local

    Repo -->|triggers build| NetlifyBuild
    GitSub -->|theme link| Repo
    Config -->|site config| NetlifyBuild
    Content -->|content input| NetlifyBuild
    Archetype -->|blueprints| NetlifyBuild
    LayoutsDefault -->|templates| NetlifyBuild
    Header -->|partial| NetlifyBuild
    Footer -->|partial| NetlifyBuild
    Analytics -->|partial| NetlifyBuild
    Shortcode -->|embed code| NetlifyBuild
    CSS1 -->|styles| NetlifyBuild
    CSS2 -->|styles| NetlifyBuild
    JS1 -->|scripts| NetlifyBuild
    JS2 -->|polyfill| NetlifyBuild
    Static -->|static assets| NetlifyBuild
    Theme -->|theme code| NetlifyBuild
    Lock -->|build artifact| NetlifyBuild

    NetlifyBuild -->|"hugo build"| Public
    Public -->|deploy| CDN
    CDN -->|"HTTP GET"| Browser
    Browser -->|"analytics call"| GA
    Browser -->|"Calendly embed"| Calendly
    Lock -->|"build logs"| Grafana

    %% Click Events
    click Repo "https://github.com/ganitak/sparky/tree/main/JB-electricite/"
    click GitSub "https://github.com/ganitak/sparky/blob/main/.gitmodules"
    click Config "https://github.com/ganitak/sparky/blob/main/JB-electricite/config.toml"
    click Content "https://github.com/ganitak/sparky/tree/main/JB-electricite/content/"
    click Archetype "https://github.com/ganitak/sparky/blob/main/JB-electricite/archetypes/default.md"
    click LayoutsDefault "https://github.com/ganitak/sparky/tree/main/JB-electricite/layouts/_default/"
    click Header "https://github.com/ganitak/sparky/blob/main/JB-electricite/layouts/head/header.html"
    click Footer "https://github.com/ganitak/sparky/blob/main/JB-electricite/layouts/footer/footer.html"
    click Analytics "https://github.com/ganitak/sparky/blob/main/JB-electricite/layouts/footer/analyticstracking.html"
    click Shortcode "https://github.com/ganitak/sparky/blob/main/JB-electricite/layouts/shortcodes/target.html"
    click CSS1 "https://github.com/ganitak/sparky/blob/main/JB-electricite/assets/css/styles.css"
    click CSS2 "https://github.com/ganitak/sparky/blob/main/JB-electricite/assets/css/404.css"
    click JS1 "https://github.com/ganitak/sparky/blob/main/JB-electricite/assets/js/template.js"
    click JS2 "https://github.com/ganitak/sparky/blob/main/JB-electricite/assets/js/html5shiv.js"
    click Static "https://github.com/ganitak/sparky/tree/main/JB-electricite/static/images/"
    click Theme "https://github.com/ganitak/sparky/tree/main/JB-electricite/themes/hugo-initio/"
    click Lock "https://github.com/ganitak/sparky/blob/main/JB-electricite/.hugo_build.lock"

    %% Styles
    classDef developer fill:#cce5ff,stroke:#66b0ff
    classDef source fill:#e6ffcc,stroke:#9fff66
    classDef cicd fill:#ffe5cc,stroke:#ffb066
    classDef cdn fill:#e5ccff,stroke:#b066ff
    classDef browser fill:#fff5cc,stroke:#ffeb66
    classDef external fill:#eeeeee,stroke:#aaaaaa
```
