How joerdonfryeman/clock works
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)