heartbeat-monitor/AGENTS.md

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 (port 3005): npm run dev -- --port 3005
• Restart dev service:
  • In the running terminal: Ctrl + C
  • If port 3005 is busy: lsof -ti :3005 | xargs kill
  • Start again: npm run dev -- --port 3005
• Build check: npm run build
• Keep TypeScript build green before merging.