# Dashboard RAM Usage Card — Design Record

- **Date:** 2026-08-24
- **Status:** Approved (design review), implementation pending
- **Scope:** Mark VIII WebUI dashboard — add a RAM Usage status card between
  Disk Usage and Uptime, showing memory used / total in the same format as the
  Disk Usage card.

## 1. Goal

The dashboard (`/` → Dashboard) currently shows status cards for Clients
Connected, Handshakes Captured, Disk Usage, and Uptime. Add a RAM Usage card
positioned after Disk Usage and before Uptime, displaying `used / total` (e.g.
`120 MB / 256 MB`) to match the Disk Usage card's presentation. The Pager is a
`ramips/mt76x8` device with 256 MB RAM.

## 2. Data source

The device's memory stats come from `/proc/meminfo` (available locally, since
the webui server runs on the Pager):

- `MemTotal` — total RAM in kB
- `MemAvailable` — available RAM in kB (falls back to `MemFree`)

`used = MemTotal - MemAvailable`, matching how `free` reports usage on OpenWRT.

The health check already parses this file via `_mem_percent()` (`server.py`)
but only exposes a percentage. The status endpoint has no memory field today.

## 3. Changes

### Backend — `payload/user/remote_access/pager-webui/server.py`

- Add `mem_data()`: parse `/proc/meminfo`, return
  `{'size': total_bytes, 'used': used_bytes, 'avail': avail_bytes}` — the same
  shape as `disk_data()` (which returns `{size, used, avail}` in bytes).
  Return `{}` on parse failure, consistent with `disk_data()`.
- Wire into `status_data()` as `'mem': mem_data()`.

### Frontend — `payload/user/remote_access/pager-webui/www/js/views.js`

- Add `['mem', 'RAM Usage']` to the card `defs` array between
  `['disk', 'Disk Usage']` and `['uptime', 'Uptime']` (dashboard view).
- In the status `update()` handler, render
  `fmtBytes(s.mem.used) + ' / ' + fmtBytes(s.mem.size)`; on missing data show
  `Unavailable`; in the initial-load catch path set `—`, mirroring the disk
  card's error handling.

### Tests — `tests/test_status.py`

- Add `mem_data()` parse test using a temp fake `/proc/meminfo` file
  (the function takes an optional path argument, like `battery_data(base)`).
- Add `mem` to the `h_status` payload-shape key assertion.

## 4. Non-goals

- No memory graph/history — the Clients chart stays as is.
- No RAM percentage formatting on the card.
- No changes to the `/api/health` `mem_percent` metric.