# 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)