dandri/meshcore-analyzer
1
0
Fork 0
mirror of https://github.com/Kpa-clawbot/meshcore-analyzer.git synced 2026-03-29 04:59:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update NEW_USER_SPEC.md to reflect implemented features

Browse Source
This commit is contained in:
you
2026-03-18 19:42:36 +00:00
parent c7dc9e4b50
commit 4fb1f89bbc
1 changed files with 38 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
NEW_USER_SPEC.md
View File

@@ -1,130 +1,54 @@
# New User Experience — Build Spec
# New User Experience
## Overview
A new "home" page for the MeshCore Analyzer that serves as a **diagnostic companion** for new mesh users. The existing pages (packets, map, channels, nodes, observers, traces) remain untouched — this is a new front door.
The home page (`#/` or `#/home`) is the front door to the analyzer — a diagnostic companion for mesh users to check if their node is being heard, and a dashboard for regulars to monitor favorites.
## Architecture
- New page registered as `home` in the SPA router (hash `#/` or `#/home`)
- New file: `public/home.js` — the page module
- New file: `public/home.css` — styles (imported via `<link>` in index.html)
- New server endpoints in `server.js` for node lookup
- Default route changes from `#/packets` to `#/home`
## Features
## Page Structure
### Hero Search
- Prefix search with auto-dropdown as you type (name or public key)
- Quick stats bar: active nodes · packets today · observers online
- Results link to node health card or node detail page
### Section 1: Hero Search
- Big centered search box with placeholder: "Search by node name or public key..."
- Subtitle: "Check if your packets are reaching the mesh"
- Auto-suggest dropdown as user types (search nodes API)
- Below search: quick stats bar — "X nodes active · Y packets today · Z observers online"
- Clean, minimal. No nav clutter competing for attention.
### Node Health Cards
Shown after search or on home page for favorited nodes.
### Section 2: Node Health Card (shown after search)
Appears below search with a smooth transition. Contains:
**Status logic:**
- 🟢 HEALTHY: heard by observers in the last hour
- 🟡 DEGRADED: last heard 1-24h ago
- 🔴 SILENT: not heard in 24+ hours
**Status Banner:**
- 🟢 HEALTHY: "Heard by N observers in the last hour"
- 🟡 DEGRADED: "Last heard 3 hours ago by 1 observer"
- 🔴 SILENT: "Not heard in 24+ hours"
- Status logic: green (<1h), yellow (1-24h), red (>24h)
**Contents:** last heard, observer count, avg SNR with quality label, hop count, packets today, status reasoning text.
**Mini Map:**
- Small Leaflet map showing the node's position + observer positions that heard it
- Lines from node to observers, thickness = signal strength
- Only if node has lat/lon
### Favorites ("Your Nodes")
- Star/unstar nodes from any node detail view
- Stored in localStorage
- "Your Nodes" section on home page with live status cards
- Quick access to node detail via click
**Key Metrics (card grid):**
- Last heard: relative time
- Observers: count + names
- Avg SNR: with plain-English quality label (Excellent >10, Good 0-10, Marginal -5-0, Poor <-5)
- Hop count: typical path length
- Packets today: count
### Quick Setup Checklist
Collapsible accordion for troubleshooting:
1. Correct preset / frequency
2. Send a flood advert
3. Check repeat count
4. Nearby repeaters (link to map)
5. Frequency mismatch warning
**Recent Activity Timeline:**
- Last 10 packets from this node, shown as a simple timeline
- Each entry: time, type (ADVERT/GRP_TXT/etc), observers that heard it, hop count
- Click any packet → links to `#/packets?id=X` (existing detail view)
### Navigation Footer
Links to full dashboard pages: Map, Channels, Packet Inspector, Observers
### Section 3: Packet Journey (expandable, one click)
When user clicks a specific packet from the timeline:
- Visual representation: Node → Hop 1 → Hop 2 → Observer
- Each step shows SNR, timing
- Simple horizontal flow diagram using CSS (no canvas/SVG needed for v1)
- Educational tooltips on hover:
- "ADVERT: This tells the network your node exists"
- "3 hops: Your packet traveled through 3 repeaters"
- "SNR -2 dB: Marginal signal — a better antenna would help"
### Section 4: Quick Setup Checklist
Always visible at bottom, collapsible accordion:
**"Not seeing results? Check these:"**
1. **Correct preset?** — Show recommended presets by region (US: 910.525 MHz, SF7, BW62.5, CR5)
2. **Sent a flood advert?** — "In the MeshCore app, tap the signal icon → Flood Advert. This announces your node to the network."
3. **See 'Heard N repeats'?** — "After sending a message, the app shows how many repeaters forwarded it. 0 repeats = no one heard you."
4. **Repeaters near you?** — Link to `#/map` filtered to repeaters
5. **Right frequency?** — "If you're on old settings (SF11, BW125), you can't talk to nodes on the new recommended preset"
### Section 5: "Ready for more?" footer
Links to the full dashboard pages:
- 🗺️ Network Map — See all nodes and coverage
- 💬 Channels — Read mesh chat messages
- 📦 Packet Inspector — Deep dive into raw packets
- 📡 Observers — See who's listening
## Server API Additions
## API Endpoints
### GET /api/nodes/search?q=<query>
- Search nodes by name (partial match) or public_key (prefix match)
- Returns top 10 matches: `{ nodes: [{ public_key, name, role, lat, lon, last_seen }] }`
Prefix search by name or public key, returns top 10 matches.
**Note:** Static path `/api/nodes/search` must be defined BEFORE parameterized `/api/nodes/:pubkey` in Express routes.
### GET /api/nodes/:pubkey/health
- Returns health summary for a specific node:
```json
{
"node": { "public_key": "...", "name": "...", "role": "...", "lat": ..., "lon": ..., "last_seen": "..." },
"status": "healthy|degraded|silent",
"observers": [{ "id": "...", "lastHeard": "...", "avgSnr": ..., "avgRssi": ..., "packetCount": ... }],
"stats": {
"packetsToday": 42,
"avgSnr": 3.2,
"avgHops": 2.1,
"lastHeard": "2026-03-17T14:30:00Z"
},
"recentPackets": [
{ "id": 123, "timestamp": "...", "payload_type": 4, "hash": "...", "observer_id": "...", "snr": 3.1, "rssi": -82, "hopCount": 2 }
]
}
```
Returns health summary: node info, status, observer list with SNR/RSSI, stats, recent packets.
## DB Queries Needed (add to db.js)
### searchNodes(query, limit=10)
```sql
SELECT * FROM nodes WHERE name LIKE ? OR public_key LIKE ? ORDER BY last_seen DESC LIMIT ?
```
### getNodeHealth(pubkey)
Multiple queries:
1. Get node by pubkey
2. Get packets where decoded_json contains this pubkey (for ADVERTs) or observer patterns
3. Aggregate observer stats
4. Recent packets list
Note: Since we don't have a `source_node` column on packets, for ADVERTs we can match by decoded_json containing the pubkey. For other packet types this is harder — we may need to add a `source_pubkey` column in a future iteration. For v1, focus on ADVERT packets as the primary "was I heard?" signal, since that's exactly what new users send first.
## Styling Guidelines
- Use existing CSS variables (--bg, --text, --accent, --border, --surface-0/1/2/3, etc.)
- Dark mode must work (use var() everywhere, no hardcoded colors)
- Mobile responsive (works at 640px)
- Match existing design language but cleaner/more spacious for the landing page
- Status colors: green=#22c55e, yellow=#eab308, red=#ef4444
## File Locations
All files in `/root/.openclaw/workspace/meshcore-analyzer/`
- `public/home.js` — new
- `public/home.css` — new
- `public/index.html` — add `<link>` for home.css, add `<script>` for home.js
- `server.js` — add 2 new endpoints
- `db.js` — add 2 new query methods
- `public/app.js` — change default route from packets to home
## Files
- `public/home.js` + `public/home.css` — home page module
- `server.js` — search + health endpoints
- `db.js` — `searchNodes()` + `getNodeHealth()` queries
- `public/app.js` — default route = home