141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# 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.
|