# joerdonfryeman/clock architecture

> Architecture diagram of the GitHub repository joerdonfryeman/clock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joerdonfryeman/clock
- Repository: https://github.com/joerdonfryeman/clock

## Overview

##### What this project is (type + purpose)
This repo is a **single-process console application** (Python) that renders a **retro ASCII clock UI** in the terminal and optionally shows **system info** + **temperature** (Linux-limited). It’s packaged to run:
- directly via `python main.py`
- as OS-specific binaries (release artifacts)
- via Docker (`Dockerfile` + Docker Hub image)

##### File tree signals (how to infer architecture from structure)
Key folders/files and what they imply:

- `main.py`
Entry point. Likely wires config → creates core objects → starts render loop.

- `core/` (primary application modules)
- `core/run.py` : orchestrates the application loop (render/refresh, keyboard/stop condition)
- `core/clock.py` : time/date formatting and “digital clock” rendering logic
- `core/info.py` : system information gathering (CPU/RAM/etc), language selection (ru/en)
- `core/temperature.py` : Linux-only temperature retrieval
- `core/base.py` : shared base classes/utilities/config loader patterns
- `core/__init__.py` : module exports

- `config_files/` (configuration & assets)
- `digits.json` : ASCII digit glyph definitions
- `logos.json` : ASCII logo definitions (13x31 constraint)
- `config_files/logs/logging.json` : logging configuration

Packaging/distribution asset (not core runtime, but relevant to release builds)

- `requirements*.txt`
External deps: `psutil`, `windows-curses` (Windows terminal compatibility)

- `Dockerfile`, `.dockerignore`
Containerized deployment path.

This strongly suggests a **layered modular design**:
- “Domain”/features: clock, info, temperature
- “Presentation”: visualization/terminal rendering
- “Config/assets”: json-driven UI glyphs/logos + runtime config
- “Orchestration”: run loop

##### README insights that must appear
From README:
- Runs in Linux and Windows (with limitations)
- Temperature info only on Linux
- Stop by pressing Enter/any key (so there is input handling)
- Language ru/en for system info
- Docker usage implies stdin/stdout interaction (`-it`)
- Uses `psutil` and `windows-curses` (platform-specific rendering/input stack)

- **OS/platform as an external dependency**
- **Terminal (stdin/stdout) as the main interface**
- **psutil + (curses/windows-curses) as key libraries**
- **JSON config + JSON assets** as data sources feeding rendering

##### Entry Point
- `main.py`

##### App Orchestrator
- `core/run.py` (main loop, timing, stop condition, calls render)

##### Config & Assets Layer
- `config_files/clock_config.json`
- `config_files/digits.json`
- `config_files/logos.json`
- `config_files/logs/logging.json`

##### Feature Providers (data generation)
- `core/clock.py` (time → “digits” / string buffers)
- `core/info.py` (system stats via psutil, localized text)
- `core/temperature.py` (temperature via OS sensors; conditional on Linux)

##### External Interfaces
- Terminal UI (stdout rendering, stdin key press)
- OS (time, sensors, system stats)
- Libraries:
- `psutil`
- `curses` / `windows-curses`

- `main.py` → `core/run.py` (start application)
- `core/run.py` → Config Loader (read `clock_config.json`, logging config)
- Config Loader → `core/info.py` (language, enable/disable info)
- Config Loader → `core/temperature.py` (enable/disable temperature)
- `digits.json` → `core/clock.py` (digit glyph map)
- `logos.json` → `core/visualisation.py` (logo glyph selection by `logo_name`)
- `core/clock.py` → `core/visualisation.py` (clock render buffer)
- `core/info.py` → `core/visualisation.py` (info lines)
- `core/temperature.py` → `core/visualisation.py` (temp line(s))
- Terminal (stdin) → `core/run.py` (stop/exit trigger)
- `core/info.py` → `psutil` → OS
- `core/temperature.py` → OS sensor APIs/files (Linux) (mark as conditional)
- `core/visualisation.py` → `curses/windows-curses` → Terminal

**Architectural patterns to label explicitly:**
- **Configuration-driven UI** (JSON assets + runtime config drive rendering)
- **Platform-conditional feature** (temperature on Linux; curses variant on Windows)
- **Main loop / render loop** (run orchestrator repeatedly collects data + renders)
- **Separation of concerns**: data providers vs rendering

Goal: show how it’s executed in different environments, not internal modules.

##### Local Linux Host
- Python 3.14 runtime
- `psutil`
- `curses` (built-in)
- reads local `config_files/*`
- uses host terminal

##### Local Windows Host
- Python 3.14 runtime
- `psutil`
- `windows-curses`
- reads local `config_files/*`
- uses Windows terminal (limitations)

##### Docker Container
- Image built from `Dockerfile`
- Runs in interactive mode (`-it`) with attached stdio
- Terminal is host terminal attached to container TTY
- Temperature availability depends on what the container can see from host; call out that sensor access may differ.

(Optionally)
##### Release Binary Artifact
- Windows `.exe` / Linux `.app` (as per README “latest release”)
- Still same runtime behavior; just packaged.

- User → Terminal
- Terminal → App Process
- App Process → OS APIs (time, stats, sensors)
- App Process → stdout

##### Checklist to ensure you captured “as many components as possible”
- [ ] `main.py` entry
- [ ] `core/run.py` loop + stop condition
- [ ] config loader + `clock_config.json`
- [ ] digits asset (`digits.json`)
- [ ] logo asset (`logos.json`)
- [ ] logging config (`logging.json`)
- [ ] clock provider (`clock.py`)
- [ ] system info provider (`info.py`) + localization (ru/en)
- [ ] temperature provider (`temperature.py`) + Linux-only annotation
- [ ] external libs (`psutil`, `curses/windows-curses`)
- [ ] OS platform boundary (Linux/Windows)
- [ ] Docker deployment node (TTY attached)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Runtime Component Diagram
  %% =========================
  subgraph R["Runtime: Single-process Console App"]
    direction TB

    U["User"]:::external
    T["Terminal (stdin/stdout + TTY)"]:::external

    subgraph APP["Python Process"]
      direction TB

      M["Entry Point (main.py)"]:::orchestrator
      RUN["App Orchestrator / Main Loop (core/run.py)"]:::orchestrator

      subgraph CFG["Config & Assets (Filesystem JSON)"]
        direction TB
        BASE["Shared Base / Utilities (core/base.py)"]:::internal
        CCFG["clock_config.json (runtime settings)"]:::config
        DIG["digits.json (ASCII glyph map)"]:::config
        LOGO["logos.json (ASCII logos 13x31)"]:::config
        LCFG["logging.json (logging config)"]:::config
      end

      subgraph FEAT["Feature Providers (Data Generation)"]
        direction TB
        CLK["Clock Provider (core/clock.py)"]:::provider
        INF["System Info Provider (core/info.py)"]:::provider
        TMP["Temperature Provider (core/temperature.py)"]:::provider
      end

      VIS["Renderer / Visualisation (core/visualisation.py)"]:::presentation
      INIT["Core Package Exports (core/__init__.py)"]:::internal
    end

    subgraph EXT["External Dependencies"]
      direction TB
      OS["OS / Platform (Linux / Windows)"]:::external
      TIME["System Time"]:::external
      SENS["Sensors / Thermal (Linux only)"]:::external
      PS["psutil (library)"]:::lib
      CUR["curses / windows-curses (library)"]:::lib
    end

    %% Notes / Callouts
    N1["Note: Stop by pressing Enter/any key (stdin)"]:::note
    N2["Note: Temperature feature is Linux-only"]:::note
    N3["Note: Windows requires windows-curses"]:::note
    N4["Note: UI is configuration-driven (JSON settings + assets)"]:::note
  end

  %% Runtime flows (keep vertical)
  U -->|"uses"| T
  T -->|"key_press"| RUN
  RUN -->|"start"| VIS

  M -->|"bootstraps"| RUN
  M -->|"imports/exports"| INIT
  RUN -->|"uses_utils"| BASE

  %% Config loading
  RUN -->|"loads"| CCFG
  RUN -->|"loads"| LCFG
  CLK -->|"loads"| DIG
  VIS -->|"loads"| LOGO

  %% Config drives features
  CCFG -->|"toggles/colors/lang/logo_name"| RUN
  CCFG -->|"clock_settings"| CLK
  CCFG -->|"info_settings"| INF
  CCFG -.->|"temp_settings"| TMP

  %% Data generation -> rendering
  RUN -->|"collects_frame_data"| CLK
  RUN -->|"collects_frame_data"| INF
  RUN -.->|"collects_frame_data"| TMP

  CLK -->|"clock_buffer"| VIS
  INF -->|"info_lines (ru/en)"| VIS
  TMP -.->|"temp_lines"| VIS

  %% Rendering
  VIS -->|"render_frame (stdout)"| T
  VIS -->|"draw_calls"| CUR
  CUR -->|"tty_control"| T

  %% OS integrations
  OS -->|"provides"| TIME
  CLK -->|"reads_time"| TIME

  INF -->|"system_metrics"| PS
  PS -->|"syscalls"| OS

  TMP -.->|"reads_sensors"| SENS
  SENS -.->|"platform_conditional"| OS

  %% Notes connections
  N1 --- RUN
  N2 -.-> TMP
  N3 -.-> CUR
  N4 --- CFG

  %% =========================
  %% Deployment Diagram
  %% =========================
  subgraph D["Deployment Options"]
    direction TB

    subgraph DL["Local Linux Host"]
      direction TB
      DL_T["Host Terminal (Linux)"]:::external
      DL_APP["App Process (python main.py)"]:::orchestrator
      DL_PY["Python 3.x Runtime"]:::internal
      DL_LIBS["Deps: psutil + curses"]:::lib
      DL_FS["Local Files: config_files/*"]:::config
      DL_OS["Linux OS (time/stats/sensors)"]:::external
    end

    subgraph DW["Local Windows Host"]
      direction TB
      DW_T["Windows Terminal"]:::external
      DW_APP["App Process (python main.py)"]:::orchestrator
      DW_PY["Python 3.x Runtime"]:::internal
      DW_LIBS["Deps: psutil + windows-curses"]:::lib
      DW_FS["Local Files: config_files/*"]:::config
      DW_OS["Windows OS (time/stats)"]:::external
    end

    subgraph DC["Docker Container"]
      direction TB
      DC_IMG["Docker Image (built from Dockerfile)"]:::deploy
      DC_APP["App Process (python main.py)"]:::orchestrator
      DC_FS["Image Files: config_files/*"]:::config
      DC_TTY["Interactive TTY (-it) attached to host terminal"]:::external
      DC_NOTE["Note: Sensor access may differ in container"]:::note
    end

    subgraph DR["Release Binary Artifact"]
      direction TB
      DR_BIN["Packaged Binary (OS-specific)"]:::deploy
      DR_TERM["Host Terminal (attached)"]:::external
      DR_OS["Host OS APIs"]:::external
    end
  end

  %% Deployment flows (vertical)
  DL_T -->|"stdin/stdout"| DL_APP
  DL_APP -->|"runs_on"| DL_PY
  DL_APP -->|"uses"| DL_LIBS
  DL_APP -->|"reads"| DL_FS
  DL_APP -->|"calls"| DL_OS

  DW_T -->|"stdin/stdout"| DW_APP
  DW_APP -->|"runs_on"| DW_PY
  DW_APP -->|"uses"| DW_LIBS
  DW_APP -->|"reads"| DW_FS
  DW_APP -->|"calls"| DW_OS

  DC_TTY -->|"stdin/stdout"| DC_APP
  DC_IMG -->|"contains"| DC_APP
  DC_APP -->|"reads"| DC_FS
  DC_NOTE --- DC_APP

  DR_TERM -->|"stdin/stdout"| DR_BIN
  DR_BIN -->|"calls"| DR_OS

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click M "https://github.com/joerdonfryeman/clock/blob/master/main.py"
  click RUN "https://github.com/joerdonfryeman/clock/blob/master/core/run.py"
  click CLK "https://github.com/joerdonfryeman/clock/blob/master/core/clock.py"
  click INF "https://github.com/joerdonfryeman/clock/blob/master/core/info.py"
  click TMP "https://github.com/joerdonfryeman/clock/blob/master/core/temperature.py"
  click VIS "https://github.com/joerdonfryeman/clock/blob/master/core/visualisation.py"
  click BASE "https://github.com/joerdonfryeman/clock/blob/master/core/base.py"
  click INIT "https://github.com/joerdonfryeman/clock/blob/master/core/__init__.py"
  click CCFG "https://github.com/joerdonfryeman/clock/blob/master/config_files/clock_config.json"
  click DIG "https://github.com/joerdonfryeman/clock/blob/master/config_files/digits.json"
  click LOGO "https://github.com/joerdonfryeman/clock/blob/master/config_files/logos.json"
  click LCFG "https://github.com/joerdonfryeman/clock/blob/master/config_files/logs/logging.json"
  click DC_IMG "https://github.com/joerdonfryeman/clock/tree/master/Dockerfile"
  click DC_APP "https://github.com/joerdonfryeman/clock/tree/master/Dockerfile"
  click DC_FS "https://github.com/joerdonfryeman/clock/tree/master/Dockerfile"
  click DC_TTY "https://github.com/joerdonfryeman/clock/tree/master/Dockerfile"
  click DL_FS "https://github.com/joerdonfryeman/clock/tree/master/config_files/"
  click DW_FS "https://github.com/joerdonfryeman/clock/tree/master/config_files/"
  click DL_LIBS "https://github.com/joerdonfryeman/clock/blob/master/requirements.txt"
  click DL_PY "https://github.com/joerdonfryeman/clock/blob/master/requirements.txt"
  click DW_LIBS "https://github.com/joerdonfryeman/clock/blob/master/requirements_for_windows.txt"
  click DW_PY "https://github.com/joerdonfryeman/clock/blob/master/requirements_for_windows.txt"
  click DC_IMG "https://github.com/joerdonfryeman/clock/blob/master/.dockerignore"
  click DR_BIN "https://github.com/joerdonfryeman/clock/tree/master/icons/"

  %% =========================
  %% Styles
  %% =========================
  classDef orchestrator fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1px
  classDef provider fill:#43a047,stroke:#1b5e20,color:#ffffff,stroke-width:1px
  classDef presentation fill:#fb8c00,stroke:#e65100,color:#ffffff,stroke-width:1px
  classDef config fill:#8e24aa,stroke:#4a148c,color:#ffffff,stroke-width:1px
  classDef lib fill:#546e7a,stroke:#263238,color:#ffffff,stroke-width:1px
  classDef external fill:#eceff1,stroke:#455a64,color:#111111,stroke-width:1px
  classDef note fill:#fff3e0,stroke:#ef6c00,color:#4e342e,stroke-width:1px
  classDef deploy fill:#3949ab,stroke:#1a237e,color:#ffffff,stroke-width:1px
  classDef internal fill:#90a4ae,stroke:#37474f,color:#111111,stroke-width:1px
```
