Signed-off-by: OpenClaw Bot <ai-agent@topdoglabs.com>
This commit is contained in:
parent
5273011f2e
commit
72e6626838
44
AGENTS.md
Normal file
44
AGENTS.md
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
## Project
|
||||||
|
Heartbeat Monitor (`Next.js 15 + React 19`) for local website/app heartbeat tracking.
|
||||||
|
|
||||||
|
## Source Control Rules
|
||||||
|
- Never commit generated or dependency artifacts.
|
||||||
|
- Keep these ignored and untracked:
|
||||||
|
- `.next/`
|
||||||
|
- `node_modules/`
|
||||||
|
- `out/`, `build/`, `dist/`
|
||||||
|
- logs, local env files, OS files
|
||||||
|
- If generated folders are accidentally tracked again, untrack (keep local files):
|
||||||
|
- `git rm -r --cached .next node_modules`
|
||||||
|
|
||||||
|
## Data Contract (Do Not Break)
|
||||||
|
- Persistence files:
|
||||||
|
- `data/apps.json`
|
||||||
|
- `data/status.json`
|
||||||
|
- Keep schema backward-compatible.
|
||||||
|
- Do not rename or remove existing keys used by API/UI without a migration plan.
|
||||||
|
|
||||||
|
## API Contract (Do Not Break)
|
||||||
|
- Endpoint: `src/app/api/monitor/route.ts`
|
||||||
|
- Supported actions:
|
||||||
|
- `GET /api/monitor` returns `{ apps, status }`
|
||||||
|
- `POST action=addApp`
|
||||||
|
- `POST action=updateApp`
|
||||||
|
- `POST action=deleteApp`
|
||||||
|
- `POST action=recordStatus`
|
||||||
|
|
||||||
|
## UI/Product Guardrails
|
||||||
|
- UI must be responsive (mobile/tablet/desktop).
|
||||||
|
- Dashboard should prioritize scanability:
|
||||||
|
- KPI summary
|
||||||
|
- service health board
|
||||||
|
- compact comparison table
|
||||||
|
- recent incidents/events
|
||||||
|
- Keep live refresh behavior and avoid long single-column list regressions.
|
||||||
|
|
||||||
|
## Dev Workflow
|
||||||
|
- Start: `npm run dev`
|
||||||
|
- Build check: `npm run build`
|
||||||
|
- Keep TypeScript build green before merging.
|
||||||
140
PRD.md
Normal file
140
PRD.md
Normal file
@ -0,0 +1,140 @@
|
|||||||
|
# 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.
|
||||||
Loading…
Reference in New Issue
Block a user