heartbeat-monitor/PRD.md

Product Requirements Document (PRD)

Product Name

Heartbeat Monitor

Summary

Heartbeat Monitor is a local-first dashboard for monitoring the health of locally hosted web apps/services. It surfaces uptime, incident events, and response-time behavior in a fast, scannable UI.

Problem Statement

Developers running multiple local services need a single view to detect outages and latency issues quickly. A long, one-column list creates high cognitive load and slows triage.

Goals

• Provide real-time visibility into service health for local apps.
• Make status and incidents immediately scannable.
• Preserve existing local JSON persistence and API workflows.
• Support responsive usage across mobile, tablet, and desktop.

Non-Goals

• Multi-user authentication/authorization.
• External SaaS monitoring or cloud alert routing.
• Replacing existing data schemas with breaking changes.

Target Users

• Individual developers managing multiple local projects.
• Small teams running local dev stacks on one machine.

Core Use Cases

• View which services are up/down now.
• See average uptime and response-time trends.
• Inspect recent incidents/recoveries.
• Add/remove monitors quickly.
• Filter/search services for focused troubleshooting.

Functional Requirements

1. Data Fetching

• Poll monitor data from /api/monitor on an interval.
• Allow manual refresh.

2. Dashboard Views

• KPI summary cards:
  • healthy services
  • average uptime
  • average latency
  • incident count
• Service health board with per-service cards.
• Service comparison table for fast row-based scanning.
• Recent event feed and performance side panels.

3. Service Operations

• Add monitor via modal form.
• Delete monitor with confirmation.

4. Filtering and Search

• Filter services by all, healthy/up, down.
• Search by service name/category/description.

5. Responsiveness

• Mobile: stacked layout with horizontal overflow handling for table.
• Tablet: multi-column cards.
• Desktop: split board + right-side insight rail.

Data Model and Storage (Current Contract)

data/apps.json

{
  "apps": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "url": "string",
      "port": 3000,
      "path": "string",
      "command": "string",
      "category": "string",
      "color": "#hex",
      "enabled": true
    }
  ]
}

data/status.json

{
  "entries": [
    {
      "appId": "string",
      "timestamp": "ISO-8601 string",
      "status": "up | down",
      "responseTime": 123
    }
  ]
}

API Requirements

• Preserve endpoint: src/app/api/monitor/route.ts
• Preserve actions:
  • addApp
  • updateApp
  • deleteApp
  • recordStatus
• Preserve default GET payload shape: { apps, status }

Technical Stack

• Next.js 15 App Router
• React 19
• Tailwind CSS v4 (@tailwindcss/postcss)
• Framer Motion
• Recharts
• Lucide icons

UX Principles

• Scanability over decoration.
• Clear status semantics (healthy/down/warning).
• Dense information where needed (table), visual context where useful (cards/sparklines).
• Fast interaction with minimal clicks.

Performance and Reliability Requirements

• Keep polling lightweight and predictable.
• Handle empty states gracefully.
• Maintain type-safe data transformations.
• Ensure production build passes (npm run build).

Success Metrics

• Time-to-identify-down-service decreases.
• Fewer clicks/scroll depth for common triage tasks.
• Consistent layout quality across viewport sizes.

Risks

• Schema drift if future edits break data compatibility.
• UI regressions if responsive breakpoints are not validated.
• Accidental commits of generated files if ignore rules are bypassed.

Open Future Enhancements

• Incident duration timelines.
• Per-service detail drawer.
• Configurable polling interval.
• Optional notifications/webhooks.