Real-Time Dashboard

🏗️ @arch responds:

## /agile-explore-brainstorm — Results

### Recommendation
Node.js + Express for the server, vanilla HTML/JS for the dashboard.
Lightweight, familiar, excellent streaming support.

### Detected Stack
- Language: JavaScript (Node.js 20)
- Framework: Express 4.x
- Frontend: Vanilla HTML + CSS + JS (no build step)
- Test Framework: Jest + Supertest

/agile-setup-init       → Memory populated (project, architecture, conventions)
/agile-setup-onboard    → Coding rules generated from detected conventions
/agile-setup-health     → ✅ All checks pass

🔄 @sm responds:

This is a spike — a time-boxed investigation that produces
learnings, not production code. Let's structure the investigation:

1. Brainstorm approaches → /agile-explore-brainstorm
2. Prototype the winner → /agile-explore-spike
3. Record the decision → /agile-memory-remember

Time-box: ~15 minutes for the full spike.

🏗️ @arch responds with a scoring matrix:

## /agile-explore-brainstorm — Results

### Problem Statement
Push real-time server metrics to a read-only browser dashboard.
Constraints: unidirectional (server→client), auto-reconnect,
simple to implement.

### Approach 1: Server-Sent Events (SSE)
- Mechanism: HTTP connection held open, server sends text/event-stream
- Pros: Native browser API (EventSource), auto-reconnect built-in,
  works through proxies, simple server implementation
- Cons: Unidirectional only (server→client), text-based (no binary),
  limited to ~6 connections per domain in HTTP/1.1
- Risks: Low — mature, well-supported standard
- Effort: Small — ~50 lines of server code

### Approach 2: WebSockets
- Mechanism: Full-duplex TCP connection upgraded from HTTP
- Pros: Bidirectional, binary support, low latency
- Cons: No auto-reconnect (must implement manually), more complex
  server setup, doesn't work through some proxies, requires ws library
- Risks: Medium — reconnection logic adds complexity
- Effort: Medium — ~120 lines + reconnection handling

### Approach 3: Long Polling
- Mechanism: Client repeatedly requests, server holds response
  until data available
- Pros: Works everywhere, simple to understand
- Cons: Higher latency, more HTTP overhead, no true streaming,
  complex timeout management
- Risks: Medium — race conditions with rapid polls
- Effort: Medium — ~100 lines + timeout management

### Scoring Matrix

| Approach     | Feasibility | Maintainability | Performance | Risk | Total |
|--------------|-------------|-----------------|-------------|------|-------|
| SSE          | 9/10        | 9/10            | 8/10        | 9/10 | 35    |
| WebSockets   | 8/10        | 6/10            | 9/10        | 7/10 | 30    |
| Long Polling  | 7/10        | 5/10            | 5/10        | 7/10 | 24    |

### Recommendation
SSE wins because:
- Unidirectional fits perfectly (server→client only)
- Native browser support via EventSource API
- Auto-reconnect is built-in — zero extra code
- Simpler than WebSockets for read-only use cases

### What Would Change This
- If you need bidirectional communication → WebSockets
- If you need binary data streaming → WebSockets
- If browser support for very old browsers matters → Long Polling

⌨️ @dev builds spike prototype:

## /agile-explore-spike — Prototype Results

### What Was Built (throwaway)
- Minimal Express server with SSE endpoint
- Sends random metrics every 100ms (10/second)
- Simple HTML page with EventSource connection

### Test Results

| Test                    | Result | Notes                        |
|-------------------------|--------|------------------------------|
| 10 metrics/second       | ✅ Pass | Stable at 10/s for 5 minutes |
| Auto-reconnect          | ✅ Pass | Reconnects in ~3 seconds     |
| Browser compatibility   | ✅ Pass | Chrome, Firefox, Safari, Edge|
| Memory usage (server)   | ✅ Pass | Stable at ~25MB RSS          |
| Connection drop recovery| ✅ Pass | EventSource handles natively |

### Latency
- Average: 2ms from server emit to browser render
- P99: 8ms
- Acceptable for a metrics dashboard

### Verdict
SSE is confirmed suitable. No blockers found.

🔄 @sm: Decision recorded as ADR

## ADR-001: Use SSE for Real-Time Data Transport

### Status
Accepted

### Context
Dashboard needs to push server metrics to the browser in real-time.
Data flow is unidirectional (server→client only). Need auto-reconnect.

### Decision
Use Server-Sent Events (SSE) over WebSockets or Long Polling.

### Rationale
- SSE scored 35/40 vs WebSockets 30/40 vs Polling 24/40
- Unidirectional fits our use case perfectly
- Native auto-reconnect via EventSource API
- Spike prototype confirmed: 10 metrics/sec, 2ms latency, stable

### Consequences
- Cannot send data from browser to server over this channel
- Limited to text-based data (JSON is fine for metrics)

### Revisit If
- Need bidirectional communication
- Need binary data streaming

→ Saved to: .memory/episodic/decisions.md

📋 @po responds:

## /agile-story-create — Story Created

### Story US-001
**As a** dashboard consumer,
**I want** an SSE endpoint that streams server metrics every 2 seconds,
**so that** I can receive live CPU, memory, uptime, and request count data.

### Acceptance Criteria

**AC-1: Happy path — SSE stream delivers metrics**
- **Given** the server is running
- **When** I connect to GET /metrics/stream with Accept: text/event-stream
- **Then** I receive a new event every 2 seconds containing
  {cpu, memory, uptime, requestCount} as JSON

**AC-2: Correct SSE format**
- **Given** I am connected to the stream
- **When** an event arrives
- **Then** it uses proper SSE format (data: prefix, double newline delimiter)

**AC-3: Connection cleanup**
- **Given** a client is connected to the stream
- **When** the client disconnects
- **Then** the server cleans up the connection (no memory leak)

### Metadata
- **Points**: 3
- **Status**: Unrefined

> Added to: .memory/backlog/product.md

📋 @po responds:

## /agile-story-create — Story Created

### Story US-002
**As a** dashboard user,
**I want** a web page with live-updating metric cards,
**so that** I can monitor server health at a glance.

### Acceptance Criteria

**AC-1: Dashboard displays four metric cards**
- **Given** I open the dashboard page
- **When** the SSE connection is established
- **Then** I see four cards: CPU, Memory, Uptime, Request Count,
  each updating every 2 seconds

**AC-2: Auto-reconnect on connection drop**
- **Given** the SSE connection drops
- **When** the browser detects the disconnect
- **Then** it automatically reconnects (via EventSource native behavior)
  and resumes displaying live data

**AC-3: Visual feedback during connection**
- **Given** I open the dashboard
- **When** connection is active → show green "Connected" indicator
- **When** connection is lost → show yellow "Reconnecting..." indicator

### Metadata
- **Points**: 5
- **Status**: Unrefined

> Added to: .memory/backlog/product.md

📋 @po responds:

## /agile-story-create — Story Created

### Story US-003
**As a** dashboard user,
**I want** graceful error handling and recovery,
**so that** temporary network issues don't break my monitoring experience.

### Acceptance Criteria

**AC-1: Reconnection indicator**
- **Given** the SSE connection is lost
- **When** the browser is attempting to reconnect
- **Then** a "Reconnecting..." banner is displayed

**AC-2: Successful recovery**
- **Given** the connection was lost and is now restored
- **When** the SSE stream resumes
- **Then** the banner disappears and metrics resume updating

**AC-3: Maximum retry with fallback**
- **Given** the connection has failed repeatedly
- **When** reconnection attempts exceed a threshold
- **Then** show an error message with a manual "Retry" button

### Metadata
- **Points**: 3
- **Status**: Unrefined

> Added to: .memory/backlog/product.md

🔄 @sm facilitates:

## Sprint Planning Output

### Sprint Goal
"Live dashboard with auto-reconnecting SSE stream"

### Sprint Backlog
| Story  | Title                       | Points | Priority |
|--------|-----------------------------|--------|----------|
| US-001 | SSE metrics endpoint        | 3      | P1       |
| US-002 | Live dashboard UI           | 5      | P1       |
| US-003 | Error handling and recovery | 3      | P1       |

### Capacity Check
- Committed this sprint: 11 points
- Stories depend on each other: US-001 → US-002 → US-003

### Risks
- SSE approach already validated by spike — low technical risk

/agile-code-branch feature US-001 sse-metrics-endpoint
/agile-story-plan US-001

👨‍💻 @lead: Implementation Plan for US-001

Phase 1: Metrics collector
- Module to read CPU, memory, uptime, request count
- Returns a plain object with current values

Phase 2: SSE endpoint
- GET /metrics/stream
- Set headers: Content-Type text/event-stream, Cache-Control no-cache
- Send metrics every 2 seconds using setInterval
- Clean up interval on client disconnect

Phase 3: Connection management
- Track active connections
- Remove on close event

Confidence: 9/10 — spike already proved this works

🔴 RED — Write failing test for AC-1

// test/metrics-stream.test.js
test('GET /metrics/stream returns SSE with metrics', (done) => {
  const res = request(app)
    .get('/metrics/stream')
    .set('Accept', 'text/event-stream');

  const chunks = [];
  res.on('data', (chunk) => {
    chunks.push(chunk.toString());
    if (chunks.length >= 2) {
      const data = JSON.parse(chunks[1].replace('data: ', ''));
      expect(data).toHaveProperty('cpu');
      expect(data).toHaveProperty('memory');
      expect(data).toHaveProperty('uptime');
      expect(data).toHaveProperty('requestCount');
      res.abort();
      done();
    }
  });
});

// Result: ❌ FAIL — endpoint doesn't exist

🟢 GREEN — Implement SSE endpoint

// src/routes/metrics.js
router.get('/stream', (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  });

  const interval = setInterval(() => {
    const metrics = {
      cpu: os.loadavg()[0],
      memory: process.memoryUsage().heapUsed,
      uptime: process.uptime(),
      requestCount: getRequestCount()
    };
    res.write(`data: ${JSON.stringify(metrics)}\n\n`);
  }, 2000);

  req.on('close', () => clearInterval(interval));
});

// Result: ✅ PASS

🔵 REFACTOR — Extract metrics collection

// Extract to src/services/metricsCollector.js
// Tests still pass ✅

/agile-code-ci           → ✅ All green (4/4 tests passing)
/agile-code-commit       → feat(metrics): add SSE metrics streaming endpoint
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved (🟡 S2: extract interval timing to config)
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

/agile-code-branch feature US-002 dashboard-ui
/agile-story-plan US-002
/agile-code-tdd US-002
  🔴 Test: Dashboard page loads with 4 metric cards → ❌
  🟢 Create HTML with card layout + EventSource connection → ✅
  🔴 Test: Cards update when SSE event arrives → ❌
  🟢 Parse event data, update DOM elements → ✅
  🔴 Test: Connection status indicator shows state → ❌
  🟢 Add connected/reconnecting indicators → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(dashboard): add live-updating metrics UI
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (5 points)

/agile-code-branch feature US-003 error-handling
/agile-story-plan US-003
/agile-code-tdd US-003
  🔴 Test: Reconnecting banner shows on disconnect → ❌
  🟢 Add EventSource onerror handler with banner toggle → ✅
  🔴 Test: Banner disappears on successful reconnect → ❌
  🟢 Add EventSource onopen handler to hide banner → ✅
  🔴 Test: Manual retry button after max retries → ❌
  🟢 Add retry counter with fallback UI → ✅

⌨️ @dev profiles the SSE endpoint:

## /agile-code-perf — Results

### Test Configuration
- Endpoint: GET /metrics/stream
- Concurrent connections: 10, 50, 100, 200
- Duration: 30 seconds per level
- Metric interval: 2 seconds

### Results

| Connections | Avg Latency | P99 Latency | Memory (RSS) | Status |
|-------------|-------------|-------------|--------------|--------|
| 10          | 1ms         | 3ms         | 28MB         | ✅     |
| 50          | 2ms         | 6ms         | 35MB         | ✅     |
| 100         | 4ms         | 12ms        | 48MB         | ✅     |
| 200         | 8ms         | 25ms        | 72MB         | ⚠️     |

### Findings
- ✅ Stable up to 100 concurrent connections
- ⚠️ At 200 connections, memory grows linearly — each connection
  holds an open response + interval timer
- Recommendation: for production, add connection pooling or
  switch to a broadcast pattern (single interval, fan out to all)

### Optimization Applied
Refactored to single metrics interval with broadcast to all
connected clients. Re-test:

| Connections | Avg Latency | Memory (RSS) | Status |
|-------------|-------------|--------------|--------|
| 200         | 3ms         | 38MB         | ✅     |

✅ Optimization resolved the scaling concern.

/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(dashboard): add error handling with auto-recovery
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

🔄 @sm: Recalled from .memory/episodic/decisions.md

## ADR-001: Use SSE for Real-Time Data Transport

### Decision
Use Server-Sent Events (SSE) over WebSockets or Long Polling.

### Key Rationale
- Scored 35/40 vs WebSockets 30/40
- Unidirectional fits our read-only dashboard
- Native auto-reconnect via EventSource
- Spike confirmed: 10 metrics/sec, 2ms latency

### Revisit If
- Need bidirectional communication
- Need binary data streaming

## Sprint Review Report

### Sprint Goal: "Live dashboard with auto-reconnecting SSE stream"
### Sprint Goal Met: ✅ Yes

| Story  | Title                       | Points | Status      |
|--------|-----------------------------|--------|-------------|
| US-001 | SSE metrics endpoint        | 3      | ✅ Accepted  |
| US-002 | Live dashboard UI           | 5      | ✅ Accepted  |
| US-003 | Error handling and recovery | 3      | ✅ Accepted  |

### Velocity
- Committed: 11 points
- Completed: 11 points (100%)

/agile-sprint-retro       → What went well: spike de-risked the approach,
                             performance testing caught broadcast optimization
/agile-memory-learn       → Saved sprint velocity + spike effectiveness

/agile-ship-changelog     → v1.0.0: SSE endpoint, live dashboard, error handling
/agile-ship-release       → release/v1.0.0 → main, tagged, back-merged
/agile-ship-deploy        → ✅ Deployed, smoke tests passing, dashboard live