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.