From a235b26a5f7b500878bf2c99c5123efdb78b10b3 Mon Sep 17 00:00:00 2001
From: jeffrey-graham <jeffrey.graham3@gmail.com>
Date: Fri, 6 Nov 2026 21:27:20 -0500
Subject: [PATCH] Enhance documentation for React Dashboard usage

Expanded the documentation for the RPi-Monitoring React Dashboard, including prerequisites, running instructions, a PR validation checklist, and troubleshooting tips.
---
 docs/DASHBOARD.md | 67 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 5 deletions(-)

diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md
index 07fa9c6..cd5c04b 100644
--- a/docs/DASHBOARD.md
+++ b/docs/DASHBOARD.md
@@ -1,12 +1,69 @@
-# Dashboard (Manager) — RPi-NMS
+# Dashboard (Manager) — RPi-NMS (`docs/DASHBOARD.md`)
 
-This documents the React Dashboard and how managers can use it.
+Comprehensive guide for managers and reviewers to run, configure, and validate the **RPi-Monitoring React Dashboard** locally when reviewing Pull Requests.
 
-## Start
-1. Ensure backend is accessible (default: http://localhost:8000)
-2. From repo root:
+---
 
+## 1. Prerequisites
+
+- **Node.js** `>= 18.x` and **npm** `>= 9.x`
+- **Backend API** running locally (`http://localhost:8000`) via Docker Compose or Uvicorn:
+  ```bash
+  docker compose up -d
+  # OR locally:
+  uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+  ```
+
+---
+
+## 2. Running the React Dashboard Locally
+
+From the repository root:
+
+```bash
 cd frontend
 npm install
 npm start
+```
+
+The development server starts at **`http://localhost:3000`** and proxies API calls to `http://localhost:8000` (configurable via `REACT_APP_API_URL`).
+
+### Custom Backend URL
+
+```bash
+REACT_APP_API_URL=http://192.168.1.10:8000 npm start
+```
+
+---
+
+## 3. Manager PR Validation Checklist
+
+When validating a contributor's Pull Request affecting the dashboard or backend API:
+
+1. **Checkout the PR branch:**
+   ```bash
+   gh pr checkout <PR_NUMBER>
+   ```
+2. **Start Backend & Frontend:**
+   - Verify `GET http://localhost:8000/docs` responds (`200 OK`).
+   - Run `npm install && npm start` inside `frontend/`.
+3. **Verify Core Views:**
+   - **Device List & Status Badges:** Online/Offline indicators, CPU temperature, memory, and disk usage gauges update cleanly.
+   - **Auto-Discovery & SNMP:** Newly discovered Raspberry Pi nodes appear without console errors.
+   - **Alert Rules:** Triggering a threshold highlights the alert state in the UI.
+4. **Production Build Verification:**
+   ```bash
+   cd frontend
+   npm run build
+   ```
+   Ensure the production bundle compiles with zero TypeScript/ESLint errors.
+
+---
+
+## 4. Troubleshooting
 
+| Symptom | Cause | Fix |
+| :--- | :--- | :--- |
+| `Network Error` / Empty device table | Backend not reachable or CORS blocked | Ensure backend runs on `:8000` and `REACT_APP_API_URL` matches |
+| `ENOSPC` / watcher error on Linux | Low `fs.inotify.max_user_watches` | Run `sudo sysctl fs.inotify.max_user_watches=524288` |
+| Port `3000` already in use | Another dev server running | Run `PORT=3001 npm start` |