hdmistat/DESIGN.md
sneak 402c0797d5 Initial implementation of hdmistat - Linux framebuffer system stats display
Features:
- Beautiful system statistics display using IBM Plex Mono font
- Direct framebuffer rendering without X11/Wayland
- Multiple screens with automatic carousel rotation
- Real-time system monitoring (CPU, memory, disk, network, processes)
- Systemd service integration with install command
- Clean architecture using uber/fx dependency injection

Architecture:
- Cobra CLI with daemon, install, status, and info commands
- Modular design with separate packages for display, rendering, and stats
- Font embedding for zero runtime dependencies
- Layout API for clean text rendering
- Support for multiple screen types (overview, top CPU, top memory)

Technical details:
- Uses gopsutil for cross-platform system stats collection
- Direct Linux framebuffer access via memory mapping
- Anti-aliased text rendering with freetype
- Configurable screen rotation and update intervals
- Structured logging with slog
- Comprehensive test coverage and linting setup

This initial version provides a solid foundation for displaying rich
system information on resource-constrained devices like Raspberry Pis.
2025-07-23 12:55:42 +02:00

107 lines
3.2 KiB
Markdown

# hdmistat Design Document
## Overview
hdmistat is a golang daemon that displays system statistics on Linux framebuffers using beautiful bitmap graphics rendered with the IBM Plex Mono font in ultralight weight. It's designed for resource-constrained systems like Raspberry Pis that don't run X11 or Wayland.
## Architecture
### Core Components
1. **Display Package** (`internal/display`)
- Interfaces with Linux framebuffer devices
- Handles raw image display
- Manages framebuffer memory mapping
2. **Layout Package** (`internal/layout`)
- Provides simple text rendering API
- Handles font rendering with IBM Plex Mono ultralight
- Offers drawing primitives for creating clean layouts
- Abstracts away complex image manipulation
3. **Stat Collector Package** (`internal/statcollector`)
- Collects system information (CPU, memory, disk, network, processes)
- Returns structured data for rendering
- Uses gopsutil for cross-platform system stats
4. **Renderer Package** (`internal/renderer`)
- Converts system stats to images using the layout API
- Manages different screen types
- Handles screen-specific rendering logic
5. **Carousel System** (`internal/app`)
- Manages multiple screens
- Handles automatic screen rotation
- Coordinates between collectors, renderers, and display
### Dependency Injection
Uses uber/fx for dependency injection to:
- Wire together components automatically
- Manage component lifecycle
- Enable clean separation of concerns
- Facilitate testing and modularity
### CLI Structure
Uses cobra for command handling:
- `hdmistat daemon` - Main daemon that takes over framebuffer
- `hdmistat install` - Installs systemd unit files and enables the service
- `hdmistat status` - Shows current daemon status
- `hdmistat info` - Displays system information in terminal
### Screen Types
1. **Overview Screen** - Shows:
- Hostname
- Memory usage
- CPU usage
- Temperatures
- Disk usage
- Network interface status (link speeds, IPs, current speeds)
2. **Configurable Detail Screens**:
- Top processes by memory
- Top processes by CPU
- Largest files
- Network traffic details
- Custom user-defined screens
### Configuration
- YAML-based configuration file
- Specifies which screens to show
- Screen rotation timing
- Custom screen definitions
- Font size and layout preferences
### Logging
- Uses log/slog for structured logging
- Different log levels for debugging
- Logs to systemd journal when running as service
### Font Rendering
- IBM Plex Mono font in ultralight weight
- Embedded in binary for zero dependencies
- Anti-aliased rendering for crisp text
- Configurable sizes
### Communication
Components communicate via interfaces:
- `Display` - Show images on framebuffer
- `Collector` - Gather system information
- `Renderer` - Convert data to images
- `Screen` - Define what to display
- `Layout` - Text and graphics rendering
## Implementation Notes
- All types defined in their respective packages (no separate types package)
- Graceful shutdown handling
- Error recovery to prevent framebuffer corruption
- Efficient memory usage for resource-constrained systems
- No external font dependencies (embedded assets)