# wekers/conky architecture

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

- Interactive diagram: https://gitdiagram.com/wekers/conky
- Repository: https://github.com/wekers/conky

## Overview

##### Project type and purpose
- This is an open-source “plugin”/configuration bundle for Conky, a desktop system-monitoring tool.

##### File structure
- Top-level scripts and configs:
- Multiple .conkyrc files (.conkyrc, .conkyrc_720p, .conkyrc_1366x768p, .conkyrc_2k) – resolution-specific Conky configurations
- conky.lua – Lua extension module for Conky (custom functions, temperature logic)
- Shell scripts under project root (time.sh, GetMoon.sh, lune_die.sh) and moon.pl – fetch & parse external data (weather, moon phases)
- printscreen/ – sample screenshots
- conky-1.9.0.tar.bz2 – Conky source archive for custom build
- No traditional “frontend/backend” directories – it’s a single Conky client embedding scripts.

##### README
- Describes dependencies (Lua, xmllint, curl, hddtemp, sensors, Perl module Astro::MoonPhase).
- Explains how .conkyrc invokes `execi`, `lua_parse`, and `${image}` calls to shell scripts and Lua functions.
- Describes external services: OpenWeatherMap API (XML), die.net JavaScript-protected moon pages (replaced by Perl), local sensors via hwmon.

a. Main components
1. Conky Engine (conky binary)
2. Conky Configuration (.conkyrc*, conky.lua)
3. Shell & Perl Data-Fetch Scripts
- time.sh → OpenWeatherMap (weather, forecast)
- lune_die.sh + moon.pl → Astro::MoonPhase → moon phases
- GetMoon.sh (legacy)
4. Local OS Sensors & Utilities
- hwmon (sensors)
- hddtemp daemon
- nvidia-smi / nvidia-settings
6. External Services
- OpenWeatherMap REST API
- CPAN repository (Astro::MoonPhase)
b. Relationships & Data Flows
- Conky Engine reads .conkyrc →
- invokes `lua_parse` on conky.lua → reads hwmon, hddtemp, GPU metrics → returns values to Conky
- Conky Engine outputs overlay to X11 server on user’s desktop.
- Build process (offline): conky-1.9.0.tar.bz2 → configure/make → custom Conky binary with Lua & weather modules.

c. Architectural patterns & design principles
- Plugin-style: Conky core + scripts + Lua modules are loosely coupled.
- Polling model: `execi` triggers periodic data fetch.
- Cache intermediary: external data is first written locally then consumed by Conky.
- Separation of concerns:
- Data fetching/parsing in shell/Perl
- Presentation in .conkyrc and images
- Computation (temperatures, moon phase) in Lua/Perl

d. Key technologies & libraries
- Conky (C) with Lua support
- Bash scripts with curl, xmllint, imagemagick (optional)
- Perl + Astro::MoonPhase
- Linux hwmon/sysfs, hddtemp, nvidia CLI tools
- OpenWeatherMap XML API

##### Detail
- Every script invocation and data path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Central orchestrator
    ConkyEngine["Conky Engine"]:::conkyEngine

    %% Configuration cluster
    subgraph "Configuration" 
        direction TB
        ConkyRC[".conkyrc"]:::config
        ConkyRC720p[".conkyrc_720p"]:::config
        ConkyRC1366[".conkyrc_1366x768p"]:::config
        ConkyRC2k[".conkyrc_2k"]:::config
        conkyLua["conky.lua"]:::config
    end

    %% Scripts cluster
    subgraph "Data Fetch & Parsing Scripts"
        direction TB
        TimeSH["time.sh"]:::script
        GetMoon["GetMoon.sh"]:::script
        LuneDie["lune_die.sh"]:::script
        MoonPL["moon.pl"]:::script
    end

    %% OS Utilities
    subgraph "OS Utilities" 
        direction TB
        Sensors["hwmon/sensors"]:::os
        HddTemp["hddtemp"]:::os
        NvidiaCLI["nvidia-smi / nvidia-settings"]:::os
    end

    %% Cache and Assets
    Cache["(Cache & Asset Store)"]:::cache

    %% External Services
    subgraph "External Services"
        direction TB
        OpenWeather["OpenWeatherMap API"]:::ext
        CPAN["CPAN (Astro::MoonPhase)"]:::ext
    end

    %% Build process
    Build["conky-1.9.0.tar.bz2"]:::build

    %% Output
    X11["X11 Server Display"]:::ext

    %% Relationships
    ConkyEngine -->|"reads"| ConkyRC
    ConkyEngine -->|"reads"| ConkyRC720p
    ConkyEngine -->|"reads"| ConkyRC1366
    ConkyEngine -->|"reads"| ConkyRC2k
    ConkyEngine -->|"lua_parse"| conkyLua
    conkyLua -->|"reads metrics"| Sensors
    conkyLua -->|"reads metrics"| HddTemp
    conkyLua -->|"reads metrics"| NvidiaCLI

    ConkyEngine -->|"execi 300s"| TimeSH
    TimeSH -->|"curl fetch"| OpenWeather
    TimeSH -->|"writes XML/PNG"| Cache

    ConkyEngine -->|"execi 3600s"| LuneDie
    LuneDie -->|"uses module"| CPAN
    LuneDie -->|"computes phases"| MoonPL
    MoonPL -->|"writes results"| Cache

    ConkyEngine -->|"reads images/icons"| Cache
    ConkyEngine -->|"outputs overlay"| X11

    Build -->|"compile/custom build"| ConkyEngine

    %% Click Events
    click ConkyRC "https://github.com/wekers/conky/blob/master/.conkyrc"
    click ConkyRC720p "https://github.com/wekers/conky/blob/master/.conkyrc_720p"
    click ConkyRC1366 "https://github.com/wekers/conky/blob/master/.conkyrc_1366x768p"
    click ConkyRC2k "https://github.com/wekers/conky/blob/master/.conkyrc_2k"
    click conkyLua "https://github.com/wekers/conky/blob/master/conky.lua"
    click TimeSH "https://github.com/wekers/conky/blob/master/time.sh"
    click GetMoon "https://github.com/wekers/conky/blob/master/GetMoon.sh"
    click LuneDie "https://github.com/wekers/conky/blob/master/lune_die.sh"
    click MoonPL "https://github.com/wekers/conky/blob/master/moon.pl"
    click Cache "https://github.com/wekers/conky/tree/master/images/"
    click Cache "https://github.com/wekers/conky/tree/master/images/wind/"
    click Build "https://github.com/wekers/conky/blob/master/conky-1.9.0.tar.bz2"
    click README["README.md"] "README.md"
    click LICENSE["LICENSE"] "LICENSE"

    %% Styles
    classDef conkyEngine fill:#add8e6,stroke:#000;
    classDef config fill:#90ee90,stroke:#000;
    classDef script fill:#ffff99,stroke:#000;
    classDef cache fill:#ffa500,stroke:#000,shape:cylinder;
    classDef ext fill:#c0c0c0,stroke:#000;
    classDef os fill:#f0e68c,stroke:#000,stroke-dasharray: 5 5;
    classDef build fill:#d3d3d3,stroke:#000;
```
