mirror of
https://github.com/Kpa-clawbot/meshcore-analyzer.git
synced 2026-06-06 04:21:46 +00:00
you
133 lines
7.9 KiB
Markdown
133 lines
7.9 KiB
Markdown
# Proposal: Terminal/TUI Interface for CoreScope
|
|
|
|
**Status:** Approved for MVP
|
|
**Issue:** TBD
|
|
|
|
## Problem
|
|
|
|
CoreScope's web UI requires a browser. Operators managing remote mesh deployments often work over SSH — headless servers, Raspberry Pis, field laptops with spotty connectivity. They need to check mesh health, view packet flow, and diagnose issues without opening a browser.
|
|
|
|
## Vision
|
|
|
|
A terminal-based user interface (TUI) that connects to a CoreScope instance's API and renders key views directly in the terminal. Think `htop` for mesh networks.
|
|
|
|
---
|
|
|
|
## Expert Review
|
|
|
|
### Carmack (Performance / Data Flow)
|
|
|
|
- **bubbletea is fine for this.** The TUI is a thin API consumer — it's not processing 7.3M observations locally. The server does the heavy lifting; the TUI just renders summary data from `/api/observers/metrics/summary` (dozens of rows, not millions). No performance concern here.
|
|
- **WebSocket in a TUI — one gotcha:** reconnection. SSH sessions drop, networks flake. The TUI MUST have automatic reconnect with exponential backoff. Don't let a dropped WS kill the whole UI — show a "reconnecting..." status and keep the last-known state visible.
|
|
- **Memory footprint:** Should be trivial. The TUI holds at most a few hundred packets in a ring buffer for the live feed + summary stats. Target <20MB RSS. bubbletea itself is lightweight. The danger is unbounded packet accumulation — use a fixed-size ring buffer (e.g., last 1000 packets) for the live feed, not an ever-growing slice.
|
|
- **Batch WS messages.** Don't re-render on every single packet. Coalesce WS messages and re-render at most 10fps (every 100ms). Terminal rendering is slow — flooding it with updates causes flicker and CPU burn.
|
|
|
|
### Torvalds (Simplicity / Scope)
|
|
|
|
- **The scope is too big for an MVP.** Node detail view, sparklines, SSH server mode, multi-instance, export — delete all of that from M1. You need TWO views to prove this works: fleet dashboard table and live packet feed. That's it.
|
|
- **bubbletea vs tview:** bubbletea. Not because Elm-architecture is "clean" — because it's what the Go community actually uses now, the examples are good, and lipgloss makes table rendering trivial. Don't overthink this.
|
|
- **Over-engineering risk is HIGH.** The proposal describes 4 views, stretch features, and SSH server mode before a single line of code exists. Build the two-view demo. Ship it. Then decide what's next based on whether anyone actually uses it.
|
|
- **Same repo, `cmd/tui/`.** Don't create a separate repo for what's going to be 500 lines of Go initially. It shares the same API types. Keep it together.
|
|
- **Kill the "Open Questions" section.** Answer them: Target user = anyone with SSH access. M1 = dashboard + live feed. Same repo. Name = `corescope-tui`. Done. Stop discussing, start building.
|
|
|
|
### Doshi (Strategy / Prioritization)
|
|
|
|
- **This is an N (Neutral) feature, not an L.** It doesn't change CoreScope's trajectory — the web UI already works. But it's a solid N: it unlocks a real use case (SSH-only operators) and proves CoreScope's API is a proper platform, not just a web app backend.
|
|
- **The MVP that proves the concept:** Can an operator SSH into a Pi, run `corescope-tui --url http://analyzer:3000`, and immediately see fleet health + live packets? If yes, the concept is proven. Everything else (node detail, sparklines, alerting) is M2+.
|
|
- **Defer list:** Node detail view, RF sparklines, SSH server mode, multi-instance, export, mouse support, true-color fallback, alerting. ALL of these are M2 or later.
|
|
- **Pre-mortem — why would this fail?**
|
|
1. Nobody uses it because the web UI is good enough (likely for most users — that's fine, this is for the SSH-only niche)
|
|
2. The API doesn't return what the TUI needs in the right shape (validate this FIRST — curl the endpoints before writing any TUI code)
|
|
3. Scope creep kills the demo — someone adds "just one more view" and it's never done
|
|
- **Opportunity cost:** Low. This is a day of work for the MVP. The API already exists. The risk is spending a week on polish nobody asked for.
|
|
|
|
---
|
|
|
|
## MVP Definition (Demo Target)
|
|
|
|
**Goal:** A working two-view TUI that connects to any CoreScope instance and displays real-time mesh data in a terminal. Buildable in one focused session.
|
|
|
|
### View 1: Fleet Dashboard (default)
|
|
```
|
|
┌─ CoreScope TUI ──────────────────────────────────────────┐
|
|
│ Connected: analyzer.00id.net | Observers: 35 | ● Live │
|
|
├──────────────────────────────────────────────────────────┤
|
|
│ Observer │ Nodes │ Pkts/hr │ NF │ Status │
|
|
│ GY889 Repeater │ 142 │ 312 │ -112 │ ● active │
|
|
│ C0ffee SF │ 89 │ 201 │ -108 │ ● active │
|
|
│ ELC-ONNIE-RPT-1 │ 67 │ 156 │ -95 │ ▲ warning │
|
|
│ Bar Repeater │ 12 │ 3 │ -76 │ ▼ stale │
|
|
└──────────────────────────────────────────────────────────┘
|
|
Tab: [Dashboard] [Live Feed] q: quit ?: help
|
|
```
|
|
|
|
- **Data source:** `GET /api/observers/metrics/summary`
|
|
- **Refresh:** Poll every 5s (simple, no WS needed for this view)
|
|
- **Sort:** By observer name initially. Stretch: column sort with arrow keys.
|
|
|
|
### View 2: Live Packet Feed
|
|
```
|
|
┌─ Live Feed ──────────────────────────────────────────────┐
|
|
│ 14:32:01 ADVERT GY889 Repeater → 3 hops -112dB │
|
|
│ 14:32:02 GRP_TXT #test "hello world" → 5 hops -98dB │
|
|
│ 14:32:03 TXT_MSG [encrypted] → 2 hops -105dB │
|
|
│ 14:32:04 CHAN #sf "anyone on?" → 8 hops -91dB │
|
|
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
|
|
└──────────────────────────────────────────────────────────┘
|
|
Tab: [Dashboard] [Live Feed] p: pause q: quit
|
|
```
|
|
|
|
- **Data source:** WebSocket (`/ws`)
|
|
- **Buffer:** Ring buffer, last 500 packets max
|
|
- **Render:** Coalesce updates, re-render at most 10fps
|
|
- **Reconnect:** Auto-reconnect with exponential backoff (1s, 2s, 4s, max 30s)
|
|
|
|
### What's NOT in MVP
|
|
- Node detail view
|
|
- RF sparklines
|
|
- SSH server mode (`--serve-ssh`)
|
|
- Multi-instance support
|
|
- Export to CSV/JSON
|
|
- Mouse support
|
|
- Alerting / terminal bell
|
|
- Color theme configuration
|
|
- Custom filters (/ to filter)
|
|
|
|
### Technical Decisions (Resolved)
|
|
| Question | Answer |
|
|
|---|---|
|
|
| Target user | SSH operators, power users, field techs |
|
|
| Library | bubbletea + lipgloss |
|
|
| Location | `cmd/tui/` in same repo |
|
|
| Binary name | `corescope-tui` |
|
|
| Min terminal | 256-color, 80x24 |
|
|
| State | Stateless — pure API consumer, no local DB |
|
|
|
|
### Implementation Plan
|
|
1. Scaffold `cmd/tui/main.go` — flag parsing (`--url`), bubbletea app init
|
|
2. Fleet dashboard model — fetch `/api/observers/metrics/summary`, render table
|
|
3. Live feed model — WebSocket connect, ring buffer, packet rendering
|
|
4. Tab switching between views
|
|
5. Status bar (connection state, help hints)
|
|
6. Test against `https://analyzer.00id.net`
|
|
|
|
---
|
|
|
|
## Future Milestones (post-MVP, not scheduled)
|
|
|
|
### M2: Navigation & Detail
|
|
- Node detail view (select observer → see its packets/neighbors)
|
|
- Keyboard navigation (j/k, Enter, Esc)
|
|
- `/` to filter packets
|
|
|
|
### M3: Visualization
|
|
- RF noise floor sparklines (`▁▂▃▅▇█`)
|
|
- Health history over time
|
|
- Color theme support
|
|
|
|
### M4: Advanced
|
|
- SSH server mode (`--serve-ssh :2222`)
|
|
- Multi-instance tabs
|
|
- Export current view to stdout (CSV/JSON)
|
|
- Desktop notifications on anomalies
|