Developer Guide

Orientation for engineers working on the monitoring subsystem. Deep reference lives in the repo docs linked at the bottom — this page is the map, not a copy.

Architecture & data flow

Monitoring data moves in one direction:

Vendor APIs (Ruijie / Omada / Huawei)
  ↓  cron collectors (separate dyno)
PostgreSQL (snapshots + live state)
  ↓  react-query hooks
NOC UI

Collectors run on a separate service, not the web app. The app only reads from the cache — it never calls vendor APIs on request (except token endpoints).
AI insights degrade gracefully: if ANTHROPIC_API_KEY is absent or the API errors, triage falls back to deterministic heuristics and never throws.
The escalation ladder is a single source of truth — ESCALATION_POLICY in lib/ai/escalation.ts. Update that one constant and every prompt that injects it inherits the change.

Key files & directories

app/noc/[projectId]/ — NOC dashboard, daily report, helpdesk pages
app/api/noc/ — NOC endpoints (sites, uptime, network, down-sites, insights, daily)
components/noc/ — KPI strip, sites map, charts, insights, daily briefing
lib/ai/ — outage clustering, daily report, site behavior, escalation policy
lib/hooks.ts — react-query hooks (useNocSites, useNocDaily, …)
lib/endpoint.ts — the HTTP wrapper (rate limiting, audit logging, error handling)
prisma/schema.prisma — data models (Groups, Devices, snapshots, AiInsight, …)
types/noc.ts, types/insights.ts — response and outage/report types
app/wiki/ + components/wiki/ — this documentation

Run it locally

Install deps — npm install (auto-runs prisma generate via postinstall).
Set env vars in .env: DATABASE_URL + DIRECT_URL (Postgres), JWT_SECRET / JWT_REFRESH_SECRET, ANTHROPIC_API_KEY (optional — AI degrades without it), the Google Maps key, and CRON_* for the collector service.
Start the dev server — npm run dev (Turbopack, localhost:3000).
Build / lint — npm run build, npm run lint.

Architecture & data flow

Key files & directories

Run it locally

More documentation (in the repo)