sloptop/PLAN.md

TUI Resource Monitor Plan

Language Choice: Rust

Why Rust for this:

• Produces a single native binary easily (great for self-contained executables).
• Strong ecosystem for TUIs (ratatui, crossterm) and system stats (sysinfo).
• Good performance and low runtime overhead for frequent refresh loops.

---

Product goals

What “good” looks like

• Instant readability: at-a-glance totals + per-core detail without toggles.
• htop-like process view by default: sortable, scrollable, fast.
• Responsive layout: works on narrow terminals without becoming unusable.
• Low flicker + smooth updates: stable layout, minimal reflow between ticks.
• Beautiful defaults: clean spacing, consistent borders, and clear hierarchy.

Core metrics (MVP+)

• CPU: total + per-core bars, load averages, process count.
• Memory: used/total bar, swap used/total bar.
• Disk: per-mount bars (used/total) + optional IO rate later.
• Network: RX/TX rate (small footprint) + totals in a compact detail pane.
• Uptime + refresh interval.

---

Architecture

Modules

• collectors/: system sampling + delta/rate calculations (network rates, etc).
• state/: normalized app state for rendering (no sysinfo types in UI).
• ui/: layout + widgets (bars, tables, header/footer).
• input/: keybindings + focus handling.
• config/: CLI flags + optional persisted config.

Data model notes

• Keep a ring buffer of the last N samples for rate calculations and future sparklines.
• Store both instant values (CPU%, mem used) and derived values (RX KiB/s).
• Separate “current tick state” from “UI selection state” (process selection, sort, scroll).

---

UI / UX layout (target default)

Default screen (htop-inspired)

• Header (1 line): hostname, uptime, refresh interval, procs, load(1m/5m/15m).
• Top section (CPU):
  • First row: Total CPU bar + total %.
  • Next rows: Per-core bars (wrap to multiple rows on wide terminals; collapse to fewer rows on narrow terminals).
• Middle section:
  • Memory bar (used/total + %), Swap bar (used/total + %).
  • Disk bars: one row per mount (or top N by usage), showing used/total + %.
• Bottom section (Process table, default on):
  • Columns: PID, CPU%, MEM%, RSS, STATE, USER (optional), COMMAND (truncated).
  • Scrolling + selection highlight.
• Right sidebar (small): Network
  • Compact: RX rate, TX rate (e.g., “RX 5.6 KiB/s | TX 5.7 KiB/s”).
  • Optional detail toggle: totals, interface name(s).

Visual design guidelines (be specific)

• Consistent padding inside blocks (at least 1 cell margin).
• Fewer heavy borders: prefer thin borders + whitespace hierarchy.
• Aligned numbers: right-align percentages and sizes; fixed-width columns where possible.
• Bars
  • Use Gauge-style bars with labels like 59% 2.3 GiB / 3.8 GiB.
  • Clamp + smooth values slightly to avoid jitter (optional).
• Color & emphasis
  • One accent color for active focus/selection.
  • Subtle dim styling for labels; brighter for values.
  • Avoid rainbow; keep it calm and readable.

Responsiveness rules

• Narrow terminals:
  • Collapse per-core section to fewer rows (or show top K cores + “+N more”).
  • Reduce disk mounts shown to top N; hide least relevant columns in process table (e.g., USER).
  • Keep process table visible unless terminal is extremely small (then show summary-only mode).

---

Interaction model (baseline)

• q quit
• p pause/resume
• + / - change refresh interval
• Tab switch focus (summary panes ↔ process table)
• Process table:
  • ↑/↓ move selection, PgUp/PgDn scroll
  • c sort by CPU, m sort by MEM, p sort by PID
  • / filter (optional, can land after MVP)
• d toggle detail panes (e.g., expanded network / disk details)

---

Delivery plan (sprints)

Sprint 0 (done)

• Basic Rust program compiles and shows core resource usage.
• Responsive layout baseline exists.

Sprint 1 (next): “Better default screen”

Goal: The default view matches the desired htop-like workflow.

• Show process list by default (table + selection + scrolling).
• Keep existing total CPU but add per-core bars by default.
• Convert memory, swap, and disk to bars with used/total labels.
• Make network section smaller (compact sidebar or single-row block).
• Visual polish pass: spacing, alignment, consistent borders, calmer palette.
• Add stable refresh loop (avoid flicker; only redraw when needed).

Acceptance criteria

• At 80×24 terminal, user can see: total CPU + some per-cores, memory bar, at least 1–2 disk bars, and a usable process table.
• Process table supports scrolling and at least one sort (CPU).

Sprint 2: “Interaction + quality”

• Full sort options (CPU/MEM/PID) + stable sorting.
• Focus handling + keybinding help footer.
• Optional filter/search in process table.
• Delta/rate correctness tests (network rates, refresh tick stability).
• Add config via CLI flags (refresh interval, hide/show panes).

Sprint 3: “Nice-to-haves”

• Sparklines (CPU/mem/net history) using ring buffer.
• Per-process drilldown (open files, threads) where supported.
• Alerts (threshold highlights) + optional logging/export.
• Packaging: release profile, strip, optional static linking notes.

---

Quality gates

• Unit tests for delta/rate logic and formatting helpers.
• Smoke test for startup/render loop.
• cargo fmt, cargo clippy clean.
• Manual QA on terminal sizes: 80×24, 100×30, ultrawide.