# 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`
```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`
```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.