meshcore-analyzer/NODE-ANALYTICS-PLAN.md

Node Analytics Page — Implementation Plan

Overview

A dedicated per-node analytics page (#/nodes/:pubkey/analytics) showing charts, breakdowns, and computed stats. Linked from node sidebar and full-screen detail views.

Route & Navigation

• Hash route: #/nodes/:pubkey/analytics
• Entry points:
  • Sidebar detail: "📊 Analytics" button next to "📋 Copy URL"
  • Full-screen detail: same button placement
  • Direct URL (shareable)
• Back navigation: "← Back to node" link returns to #/nodes/:pubkey

API Endpoint

GET /api/nodes/:pubkey/analytics?days=7

Returns all data needed for the page in a single request. Server computes aggregations in SQLite for efficiency.

{
  "node": { "public_key": "...", "name": "...", "role": "..." },
  "timeRange": { "from": "ISO", "to": "ISO", "days": 7 },
  "activityTimeline": [
    { "bucket": "2026-03-19T10:00:00Z", "count": 5 }
  ],
  "snrTrend": [
    { "timestamp": "ISO", "snr": 11.5, "rssi": -44, "observer_id": "...", "observer_name": "..." }
  ],
  "packetTypeBreakdown": [
    { "payload_type": 4, "label": "Advert", "count": 120 },
    { "payload_type": 5, "label": "Channel Msg", "count": 45 }
  ],
  "observerCoverage": [
    { "observer_id": "...", "observer_name": "...", "packetCount": 200, "avgSnr": 8.5, "avgRssi": -60, "firstSeen": "ISO", "lastSeen": "ISO" }
  ],
  "hopDistribution": [
    { "hops": 1, "count": 150 },
    { "hops": 2, "count": 30 }
  ],
  "peerInteractions": [
    { "peer_key": "...", "peer_name": "...", "messageCount": 15, "lastContact": "ISO" }
  ],
  "computedStats": {
    "availabilityPct": 92.5,
    "longestSilenceMs": 14400000,
    "longestSilenceStart": "ISO",
    "signalGrade": "B+",
    "snrMean": 8.2,
    "snrStdDev": 3.1,
    "relayPct": 22.5,
    "totalPackets": 450,
    "uniqueObservers": 3,
    "uniquePeers": 8,
    "avgPacketsPerDay": 64.3
  },
  "uptimeHeatmap": [
    { "dayOfWeek": 0, "hour": 14, "count": 12 }
  ]
}

Server Implementation (server.js)

Add route handler at /api/nodes/:pubkey/analytics. All queries use the same LIKE-based matching as existing getNodeHealth(). Key queries:

1. activityTimeline — SELECT strftime('%Y-%m-%dT%H:00:00Z', timestamp) as bucket, COUNT(*) as count FROM packets WHERE ... AND timestamp > ? GROUP BY bucket ORDER BY bucket
2. snrTrend — SELECT timestamp, snr, rssi, observer_id, observer_name FROM packets WHERE ... AND snr IS NOT NULL ORDER BY timestamp (raw points, chart.js handles rendering)
3. packetTypeBreakdown — SELECT payload_type, COUNT(*) as count FROM packets WHERE ... GROUP BY payload_type
4. observerCoverage — SELECT observer_id, observer_name, COUNT(*), AVG(snr), AVG(rssi), MIN(timestamp), MAX(timestamp) FROM packets WHERE ... GROUP BY observer_id ORDER BY COUNT(*) DESC
5. hopDistribution — Parse path_json in JS, count hop lengths
6. peerInteractions — Parse decoded_json, extract sender/recipient pubkeys and names, aggregate
7. uptimeHeatmap — SELECT strftime('%w', timestamp) as dow, strftime('%H', timestamp) as hour, COUNT(*) FROM packets WHERE ... GROUP BY dow, hour
8. computedStats — Derived from above data:
   • availabilityPct: count distinct hours with packets / total hours in range × 100
   • longestSilenceMs: iterate timestamps, find max gap
   • signalGrade: A (snr>15, stddev<2), B (snr>8), C (snr>3), D (snr<=3)
   • relayPct: packets with hop count > 1 / total with path data × 100

Add a helper function getNodeAnalytics(pubkey, days) in db.js to keep it organized.

Frontend

New File: public/node-analytics.js

IIFE pattern matching existing pages. Registers with the router for #/nodes/:pubkey/analytics.

Layout

┌─────────────────────────────────────────────────┐
│ ← Back to SomeNodeName                          │
│                                                 │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Availability│ │ Signal Grade│ │ Packets/Day│ │
│ │    92.5%    │ │     B+      │ │    64.3    │ │
│ └─────────────┘ └─────────────┘ └────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Observers   │ │ Relay %     │ │ Longest    │ │
│ │      3      │ │   22.5%     │ │ Silence 4h │ │
│ └─────────────┘ └─────────────┘ └────────────┘ │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ Activity Timeline (bar chart, hourly)       │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌──────────────────────┐ ┌────────────────────┐ │
│ │ SNR Trend (line)     │ │ Packet Types (pie) │ │
│ └──────────────────────┘ └────────────────────┘ │
│                                                 │
│ ┌──────────────────────┐ ┌────────────────────┐ │
│ │ Observer Coverage    │ │ Hop Distribution   │ │
│ │ (horizontal bar)     │ │ (bar chart)        │ │
│ └──────────────────────┘ └────────────────────┘ │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ Uptime Heatmap (7×24 grid, GitHub-style)    │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ Peer Interactions (ranked list)             │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Time Range Selector

• Buttons: 24h | 7d | 30d | All
• Default: 7d
• Reloads data via API when changed

Chart Library

• Chart.js v4 from CDN (unpkg): https://unpkg.com/chart.js@4/dist/chart.umd.min.js
• Add <script> tag in index.html (with cache buster)
• Chart.js is ~70KB gzipped, handles all chart types needed

Chart Specifications

1. Activity Timeline (bar chart, full width)

   • X: time buckets (hourly for ≤3d, daily for >3d)
   • Y: packet count
   • Color: role color with 50% opacity
   • Tooltip: exact count + timestamp

2. SNR Trend (line chart, half width)

   • One line per observer (different colors)
   • X: timestamp, Y: SNR (dB)
   • Include a horizontal reference line at 0 dB
   • Legend shows observer names

3. Packet Type Breakdown (doughnut chart, half width)

   • Segments: Advert, Channel Msg, DM, ACK, Request, Response, etc.
   • Colors: match existing PAYLOAD badge colors
   • Center text: total count

4. Observer Coverage (horizontal bar chart, half width)

   • Bars: one per observer, length = packet count
   • Color intensity mapped to avg SNR (brighter = better signal)
   • Labels: observer name + avg SNR

5. Hop Distribution (bar chart, half width)

   • X: hop count (1, 2, 3, 4+)
   • Y: packet count
   • Simple, clean

6. Uptime Heatmap (custom canvas/div grid, full width)

   • 7 rows (Sun–Sat) × 24 columns (hours)
   • Cell color intensity = packet count for that slot
   • Tooltip: "Monday 14:00 — 12 packets"
   • Use CSS grid with inline background colors (no chart.js needed)

7. Peer Interactions (table/list, full width)

   • Ranked by message count
   • Columns: peer name, messages, last contact
   • Peer name links to their node detail page

Stat Cards

• Use CSS grid, 3 columns on desktop, 2 on tablet, 1 on mobile
• Each card: label (small, muted), value (large, bold), optional trend arrow
• Signal grade uses color coding: A=green, B=blue, C=yellow, D=red

CSS (add to style.css)

.analytics-stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-bottom: 24px; }
.analytics-stat-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px; text-align: center; }
.analytics-stat-label { font-size: 11px; text-transform: uppercase; letter-spacing: .5px; color: var(--text-muted); margin-bottom: 4px; }
.analytics-stat-value { font-size: 28px; font-weight: 700; }
.analytics-charts { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 24px; }
.analytics-chart-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
.analytics-chart-card.full { grid-column: 1 / -1; }
.analytics-chart-card h4 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: var(--text-muted); margin-bottom: 12px; }
.analytics-heatmap { display: grid; grid-template-columns: 40px repeat(24, 1fr); gap: 2px; }
.analytics-heatmap-cell { aspect-ratio: 1; border-radius: 2px; }
.analytics-heatmap-label { font-size: 10px; color: var(--text-muted); display: flex; align-items: center; }
.analytics-time-range { display: flex; gap: 8px; margin-bottom: 16px; }
.analytics-time-range button { padding: 4px 12px; border-radius: 4px; border: 1px solid var(--border); background: var(--card-bg); color: var(--text); cursor: pointer; font-size: 12px; }
.analytics-time-range button.active { background: var(--accent); color: white; border-color: var(--accent); }
@media (max-width: 768px) { .analytics-stats { grid-template-columns: repeat(2, 1fr); } .analytics-charts { grid-template-columns: 1fr; } }
@media (max-width: 480px) { .analytics-stats { grid-template-columns: 1fr; } }

Dark Mode

All colors use CSS variables. Chart.js text/grid colors should reference --text-muted and --border. Set via:

Chart.defaults.color = getComputedStyle(document.documentElement).getPropertyValue('--text-muted').trim();
Chart.defaults.borderColor = getComputedStyle(document.documentElement).getPropertyValue('--border').trim();

Files to Modify

1. db.js — Add getNodeAnalytics(pubkey, days) function
2. server.js — Add GET /api/nodes/:pubkey/analytics route
3. public/node-analytics.js — New file, full page implementation
4. public/style.css — Add analytics CSS classes
5. public/index.html — Add Chart.js CDN script + node-analytics.js script tag (with cache buster)
6. public/app.js — Add route for #/nodes/:pubkey/analytics in the router
7. public/nodes.js — Add "📊 Analytics" button to sidebar and full-screen detail views

Constraints — DO NOT TOUCH

These files/behaviors have been manually tuned. Do not modify unless explicitly part of the plan:

1. public/map.js — Map markers, disambiguation logic, route drawing. OFF LIMITS.
2. public/packets.js — Panel resize, VCR replay logic. OFF LIMITS.
3. public/app.js makeColumnsResizable() (line ~463) — Column resize steals proportionally from all right columns with 50px minimum. Do not change.
4. Existing node detail rendering in nodes.js — Only ADD the analytics button. Do not reorganize, rename, or restructure existing sections.
5. Cache busters — When modifying index.html, bump cache busters on ALL changed files using ?v=TIMESTAMP.
6. escapeHtml and timeAgo — Globals defined in app.js. Do not redefine them anywhere.
7. Router in app.js — Follow existing pattern exactly when adding the analytics route.

Implementation Order

1. Add CSS to style.css
2. Add Chart.js to index.html
3. Add getNodeAnalytics() to db.js
4. Add API route to server.js
5. Create node-analytics.js
6. Register route in app.js
7. Add analytics button to nodes.js (sidebar + full-screen)
8. Add node-analytics.js script tag to index.html with cache buster
9. Bump all modified file cache busters
10. Test: node -c on all JS files, verify no syntax errors

Testing

After implementation:

• Navigate to any node → click Analytics → page loads with charts
• Switch time ranges → data reloads
• Dark mode → charts readable
• Mobile → responsive layout
• Direct URL → page loads correctly
• Back button → returns to node detail