chore: complete v1.0 Analytics & Monitoring milestone
Archive milestone artifacts (roadmap, requirements, audit, phase directories) to .planning/milestones/. Evolve PROJECT.md with validated requirements and decision outcomes. Create MILESTONES.md and RETROSPECTIVE.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
admin
187
.planning/milestones/v1.0-phases/04-frontend/04-02-PLAN.md
Normal file
187
.planning/milestones/v1.0-phases/04-frontend/04-02-PLAN.md
Normal file
@@ -0,0 +1,187 @@
|
||||
---
|
||||
phase: 04-frontend
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on:
|
||||
- 04-01
|
||||
files_modified:
|
||||
- frontend/src/App.tsx
|
||||
autonomous: false
|
||||
requirements:
|
||||
- ALRT-03
|
||||
- ANLY-02
|
||||
- HLTH-01
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Alert banner appears above tab navigation when there are active critical alerts"
|
||||
- "Alert banner disappears immediately after admin clicks Acknowledge (optimistic update)"
|
||||
- "Monitoring tab shows health status indicators and processing analytics from Supabase backend"
|
||||
- "Non-admin user on monitoring tab sees Access Denied, not the dashboard"
|
||||
- "Alert fetching only happens for admin users (gated by isAdmin check)"
|
||||
artifacts:
|
||||
- path: "frontend/src/App.tsx"
|
||||
provides: "Dashboard with AlertBanner wired above nav and AdminMonitoringDashboard in monitoring tab"
|
||||
contains: "AlertBanner"
|
||||
key_links:
|
||||
- from: "frontend/src/App.tsx"
|
||||
to: "frontend/src/components/AlertBanner.tsx"
|
||||
via: "import and render above nav"
|
||||
pattern: "import.*AlertBanner"
|
||||
- from: "frontend/src/App.tsx"
|
||||
to: "frontend/src/components/AdminMonitoringDashboard.tsx"
|
||||
via: "import and render in monitoring tab"
|
||||
pattern: "import.*AdminMonitoringDashboard"
|
||||
- from: "frontend/src/App.tsx"
|
||||
to: "frontend/src/services/adminService.ts"
|
||||
via: "getAlerts call in Dashboard useEffect"
|
||||
pattern: "adminService\\.getAlerts"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Wire AlertBanner and AdminMonitoringDashboard into the Dashboard component in App.tsx. Add alert state management with optimistic acknowledge. Replace the monitoring tab content from UploadMonitoringDashboard to AdminMonitoringDashboard.
|
||||
|
||||
Purpose: This completes the frontend delivery of ALRT-03 (in-app alert banner), ANLY-02 (processing metrics UI), and HLTH-01 (health status UI).
|
||||
Output: Fully wired admin monitoring UI visible in the application.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/jonathan/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/jonathan/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/04-frontend/04-RESEARCH.md
|
||||
@.planning/phases/04-frontend/04-01-SUMMARY.md
|
||||
@frontend/src/App.tsx
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Wire AlertBanner and AdminMonitoringDashboard into Dashboard</name>
|
||||
<files>frontend/src/App.tsx</files>
|
||||
<action>
|
||||
Modify the Dashboard component in `frontend/src/App.tsx` with these changes:
|
||||
|
||||
**1. Add imports** (at the top of the file):
|
||||
```typescript
|
||||
import AlertBanner from './components/AlertBanner';
|
||||
import AdminMonitoringDashboard from './components/AdminMonitoringDashboard';
|
||||
```
|
||||
Import `AlertEvent` type from `./services/adminService`.
|
||||
|
||||
The `UploadMonitoringDashboard` import can be removed since the monitoring tab will now use `AdminMonitoringDashboard`.
|
||||
|
||||
**2. Add alert state** inside the Dashboard component, after the existing state declarations:
|
||||
```typescript
|
||||
const [activeAlerts, setActiveAlerts] = useState<AlertEvent[]>([]);
|
||||
```
|
||||
|
||||
**3. Add alert fetching useEffect** — MUST be gated by `isAdmin` (RESEARCH Pitfall 5):
|
||||
```typescript
|
||||
useEffect(() => {
|
||||
if (isAdmin) {
|
||||
adminService.getAlerts().then(setActiveAlerts).catch(() => {});
|
||||
}
|
||||
}, [isAdmin]);
|
||||
```
|
||||
|
||||
**4. Add handleAcknowledge callback** — uses optimistic update (RESEARCH Pitfall 2):
|
||||
```typescript
|
||||
const handleAcknowledge = async (id: string) => {
|
||||
setActiveAlerts(prev => prev.filter(a => a.id !== id));
|
||||
try {
|
||||
await adminService.acknowledgeAlert(id);
|
||||
} catch {
|
||||
// On failure, re-fetch to restore correct state
|
||||
adminService.getAlerts().then(setActiveAlerts).catch(() => {});
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**5. Render AlertBanner ABOVE the `<nav>` element** (RESEARCH Pitfall 1 — must be above nav, not inside a tab):
|
||||
Inside the Dashboard return JSX, immediately after `<div className="min-h-screen bg-gray-50">` and before the `{/* Navigation */}` comment and `<nav>` element, add:
|
||||
```jsx
|
||||
{isAdmin && activeAlerts.length > 0 && (
|
||||
<AlertBanner alerts={activeAlerts} onAcknowledge={handleAcknowledge} />
|
||||
)}
|
||||
```
|
||||
|
||||
**6. Replace monitoring tab content:**
|
||||
Change:
|
||||
```jsx
|
||||
{activeTab === 'monitoring' && isAdmin && (
|
||||
<UploadMonitoringDashboard />
|
||||
)}
|
||||
```
|
||||
To:
|
||||
```jsx
|
||||
{activeTab === 'monitoring' && isAdmin && (
|
||||
<AdminMonitoringDashboard />
|
||||
)}
|
||||
```
|
||||
|
||||
**7. Keep the existing non-admin access-denied fallback** for `{activeTab === 'monitoring' && !isAdmin && (...)}` — do not change it.
|
||||
|
||||
**Do NOT change:**
|
||||
- The `analytics` tab content (still renders existing `<Analytics />`)
|
||||
- Any other tab content
|
||||
- The tab navigation buttons
|
||||
- Any other Dashboard state or logic
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/jonathan/Coding/cim_summary/frontend && npx tsc --noEmit 2>&1 | head -30</automated>
|
||||
<manual>Run `npm run dev` and verify: (1) AlertBanner shows above nav if alerts exist, (2) Monitoring tab shows health grid and analytics panel, (3) Non-admin sees Access Denied on monitoring tab</manual>
|
||||
</verify>
|
||||
<done>AlertBanner renders above nav for admin users with active alerts; monitoring tab shows AdminMonitoringDashboard with health status and analytics; non-admin access denied preserved</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 2: Visual verification of monitoring UI</name>
|
||||
<what-built>
|
||||
Complete admin monitoring frontend:
|
||||
1. AlertBanner above navigation (shows when critical alerts exist)
|
||||
2. AdminMonitoringDashboard in Monitoring tab (health status grid + analytics summary)
|
||||
3. Alert acknowledge with optimistic update
|
||||
</what-built>
|
||||
<how-to-verify>
|
||||
1. Start frontend: `cd frontend && npm run dev`
|
||||
2. Start backend: `cd backend && npm run dev`
|
||||
3. Log in as admin (jpressnell@bluepointcapital.com)
|
||||
4. Click the "Monitoring" tab — verify:
|
||||
- Health status cards show for all 4 services (Document AI, LLM API, Supabase, Firebase Auth)
|
||||
- Each card has colored dot (green/yellow/red/gray) and last-checked timestamp
|
||||
- Analytics section shows upload counts, success/failure rates, avg processing time
|
||||
- Range selector (24h/7d/30d) changes the analytics data
|
||||
- Refresh button reloads data
|
||||
5. If there are active alerts: verify red banner appears ABOVE the tab navigation on ALL tabs (not just Monitoring)
|
||||
6. If no alerts exist: verify no banner is shown (this is correct behavior)
|
||||
7. (Optional) If you can trigger an alert (e.g., by having a service probe fail), verify the banner appears and "Acknowledge" button removes it immediately
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" to complete Phase 4, or describe any issues to fix</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- `npx tsc --noEmit` passes with no errors
|
||||
- AlertBanner renders above `<nav>` in Dashboard (not inside a tab)
|
||||
- Alert state only fetched when `isAdmin` is true
|
||||
- Optimistic update: banner disappears immediately on acknowledge click
|
||||
- Monitoring tab renders AdminMonitoringDashboard (not UploadMonitoringDashboard)
|
||||
- Non-admin monitoring access denied fallback still works
|
||||
- `npm run build` completes successfully
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Admin user sees health indicators and processing metrics on the Monitoring tab. Alert banner appears above navigation when active critical alerts exist. Acknowledge removes the alert banner immediately. Non-admin users see Access Denied on admin tabs.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/04-frontend/04-02-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user