Technical Spike

Spike Definition

Spike: Real-Time Notification Technology
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Question: Which real-time technology best fits
our notification requirements?

Requirements:
  - Low latency (under 2 seconds)
  - Moderate scale (10K concurrent users)
  - Server-to-client push (bidirectional NOT required)
  - Browser-native support preferred
  - Must work behind corporate proxies

Non-goals:
  - Chat or collaborative editing
  - Real-time data sync (CRDT/OT)

Option 1: WebSockets

WebSockets
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Protocol:    Full-duplex TCP over HTTP upgrade
  Direction:   Bidirectional
  Complexity:  High — connection management, heartbeats,
               reconnection logic, load balancer config
  Scaling:     Requires sticky sessions or pub/sub adapter
  Proxy:       Some corporate proxies block WS upgrades
  Verdict:     Overkill — we don't need bidirectional

Option 2: Server-Sent Events (SSE)

Server-Sent Events (SSE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Protocol:    HTTP long-lived connection, text/event-stream
  Direction:   Server → Client only
  Complexity:  Low — built on standard HTTP, native API
  Scaling:     Standard HTTP load balancing works
  Proxy:       Works through all HTTP proxies
  Browser:     Native EventSource API, auto-reconnect built-in
  Verdict:     Perfect fit — server push, simple, reliable

Option 3: Polling

HTTP Polling
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Protocol:    Standard HTTP GET on interval
  Direction:   Client pulls from server
  Complexity:  Lowest — just regular API calls
  Scaling:     Wasteful — N users × interval = heavy load
  Latency:     Up to 1 full interval delay
  Verdict:     Too wasteful at 10K users, poor latency

Option 4: Managed Service (Firebase / Pusher)

Managed Service (Firebase / Pusher)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Protocol:    Vendor SDK over WebSockets
  Direction:   Bidirectional (via vendor)
  Complexity:  Low to implement, high vendor lock-in
  Scaling:     Handled by vendor
  Cost:        $50-500/month at our scale
  Verdict:     Adds dependency and ongoing cost for simple need

Comparison Matrix

                    Feasibility  Complexity  Fit   Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  WebSockets           9/10        3/10      5/10   17
  SSE                  9/10        9/10      10/10  28  ← winner
  Polling              10/10       10/10     4/10   24
  Firebase/Pusher      8/10        8/10      6/10   22
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Fit = how well it matches our specific requirements
  Higher is better for all columns

SSE Prototype — 30 Lines

// spike/sse-server.js — THROWAWAY CODE
const express = require("express");
const app = express();

app.get("/notifications", (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  // Send a notification every 3 seconds
  const interval = setInterval(() => {
    const notification = {
      type: "order_update",
      message: "Order #1234 shipped",
      timestamp: new Date().toISOString()
    };
    res.write(`data: ${JSON.stringify(notification)}\n\n`);
  }, 3000);

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

app.listen(3001);

// spike/sse-client.js — THROWAWAY CODE
const source = new EventSource("/notifications");
source.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  showToast(notification.message);
};
// Auto-reconnect is built into EventSource — no extra code needed

Result: Works immediately. Auto-reconnect built in.
Time to working prototype: 15 minutes.
Lines of code: 30

WebSocket Prototype — 80 Lines

// spike/ws-server.js — THROWAWAY CODE
const WebSocket = require("ws");
const wss = new WebSocket.Server({ port: 3002 });

const clients = new Set();

wss.on("connection", (ws) => {
  clients.add(ws);
  ws.on("close", () => clients.delete(ws));

  // Heartbeat to detect dead connections
  ws.isAlive = true;
  ws.on("pong", () => { ws.isAlive = true; });
});

// Heartbeat interval
setInterval(() => {
  wss.clients.forEach((ws) => {
    if (!ws.isAlive) return ws.terminate();
    ws.isAlive = false;
    ws.ping();
  });
}, 30000);

// Broadcast notification
setInterval(() => {
  const notification = JSON.stringify({
    type: "order_update",
    message: "Order #1234 shipped",
    timestamp: new Date().toISOString()
  });
  clients.forEach((ws) => {
    if (ws.readyState === WebSocket.OPEN) ws.send(notification);
  });
}, 3000);

// spike/ws-client.js — THROWAWAY CODE
let ws;
function connect() {
  ws = new WebSocket("ws://localhost:3002");
  ws.onmessage = (event) => {
    const notification = JSON.parse(event.data);
    showToast(notification.message);
  };
  ws.onclose = () => setTimeout(connect, 1000); // manual reconnect
}
connect();

Result: Works, but adds complexity for no benefit.
  - Manual heartbeat logic required
  - Manual reconnection required
  - Load balancer needs sticky session config
  - Bidirectional capability unused
Time to working prototype: 40 minutes.
Lines of code: 80

Spike Conclusion

Spike Result: SSE Wins
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommendation: Use Server-Sent Events (SSE)

Evidence:
  1. SSE prototype: 30 lines, 15 min, works immediately
  2. WebSocket prototype: 80 lines, 40 min, added complexity
  3. SSE auto-reconnect is built into the browser API
  4. SSE works through all HTTP proxies (WebSockets may not)
  5. SSE uses standard HTTP — no special load balancer config
  6. We don't need bidirectional communication

Trade-off accepted:
  If we later need bidirectional (e.g., chat), we would
  need to add WebSockets alongside SSE. This is acceptable
  because chat is not on the roadmap.

Time spent: 2.5 hours of 4-hour timebox

ADR-007: Use SSE for Real-Time Notifications

ADR-007: Use SSE for Real-Time Notifications
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status:   Accepted
Date:     2026-04-04
Context:  Need server-to-client push for notifications
Decision: Use Server-Sent Events (SSE) over WebSockets
Reason:   Simpler, fits requirements (no bidirectional needed),
          native browser support, works through proxies

Alternatives considered:
  - WebSockets: rejected (unnecessary complexity)
  - Polling: rejected (wasteful, poor latency)
  - Firebase: rejected (vendor lock-in, cost)

Consequences:
  - If chat feature is added later, will need WebSockets too
  - SSE limited to ~6 connections per domain in HTTP/1.1
    (not a concern — we use HTTP/2)

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

Stories Created from Spike

Stories for Sprint Backlog:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 NOTIF-001: SSE notification endpoint
   As a user, I want to receive real-time notifications
   so that I see order updates without refreshing.
   AC: SSE endpoint at /api/notifications/stream,
       sends JSON events, auto-reconnects on disconnect.

📋 NOTIF-002: Notification UI component
   As a user, I want to see a notification bell with
   a badge count so that I know when new events arrive.
   AC: Bell icon in header, badge shows unread count,
       dropdown shows last 10 notifications.

📋 NOTIF-003: Notification preferences
   As a user, I want to choose which notifications I
   receive so that I'm not overwhelmed by alerts.
   AC: Settings page with toggles per notification type,
       preferences saved to user profile.