# IC³ Analytics & AI Menu Structure

Complete navigation guide for all AI-powered analytics modules integrated into IC³ Dashboard.

## 📊 MAIN NAVIGATION STRUCTURE

```
ANALYTICS & AI (Main Domain)
│
├── 📌 EXECUTIVE SUMMARY
│   └── High-level KPIs, ROI tracking, action items
│       Components:
│       - System health score
│       - Key performance indicators
│       - Monthly ROI impact
│       - Required actions queue
│
├── 🔴 ANOMALY DETECTION CENTER
│   ├── Live Anomalies (Real-time active alerts)
│   │   └── Priority queue, severity matrix, confidence levels
│   ├── Anomaly History (30/90-day archive)
│   │   └── Trends, severity distribution, top assets
│   ├── Sensor Health (Trust engine)
│   │   └── Per-sensor calibration status, drift detection
│   ├── Alert Rules Configuration
│   │   └── Threshold management, severity settings
│   └── Reports & Analytics
│       └── Export (CSV/PDF), trend analysis
│
├── 💧 LEAK & BURST DETECTION
│   ├── Live Leaks (Active network loss events)
│   │   └── Location, estimated loss rate, confidence
│   ├── History (30-day resolution tracking)
│   │   └── Total detected, avg loss, resolution rate
│   └── NRW Attribution
│       └── Water loss breakdown by source
│
├── 🔧 PUMP HEALTH MONITOR
│   ├── Fleet Overview
│   │   └── Health scores, efficiency ratings
│   ├── Pump Detail
│   │   └── Vibration, temperature, performance metrics
│   └── Predictive Maintenance
│       └── Recommendation engine, TTF (time-to-failure)
│
├── 🧪 WATER QUALITY RISK MODEL
│   ├── Real-time Parameters
│   │   └── pH, turbidity, chlorine, hardness, conductivity
│   ├── Compliance Status
│   │   └── Pass/Fail, trending, alerts
│   └── Quality Trends
│       └── 30-day patterns, anomaly correlation
│
├── 📈 DEMAND FORECASTING
│   ├── 24-hour Forecast
│   │   └── Hourly demand prediction with confidence
│   ├── Trend Analysis
│   │   └── Seasonal patterns, peak hours
│   └── Demand vs Actual
│       └── Accuracy metrics, forecast adjustment
│
├── 🔬 ROOT CAUSE ASSISTANT
│   ├── Anomaly Investigation
│   │   └── Probable cause ranking, evidence
│   ├── Correlation Analysis
│   │   └── Cross-asset impact, cascade detection
│   └── Incident History
│       └── Similar events, resolution patterns
│
└── 🎯 ENERGY OPTIMIZATION
    ├── Efficiency Metrics
    │   └── Power consumption, pump efficiency
    ├── Load Balancing
    │   └── Optimal pump scheduling
    └── Cost Analysis
        └── Monthly energy cost, optimization savings
```

---

## 🎨 COMPONENT FILE STRUCTURE

```
frontend/src/modules/analytics/ai/
│
├── index.ts (Main exports)
│
├── anomaly/
│   ├── AnomalyDetectionDashboard.tsx (Main container)
│   ├── hooks/
│   │   └── useAnomalyDetection.ts (Data fetching + transformation)
│   ├── components/
│   │   ├── AnomalyKPICards.tsx
│   │   ├── AnomalyTable.tsx
│   │   ├── AnomalyDetailPanel.tsx
│   │   ├── SeverityMatrix.tsx
│   │   ├── AnomalyHistoryTab.tsx
│   │   ├── AlertRulesConfig.tsx
│   │   ├── SensorHealthScorecard.tsx
│   │   └── AnomalyReports.tsx
│   ├── services/
│   │   └── anomalyService.ts (API client)
│   ├── types.ts (TypeScript interfaces)
│   ├── styles/
│   │   └── anomalyDetection.module.css
│   └── index.ts
│
├── leak/
│   └── LeakBurstClassifier.tsx
│
├── pump/
│   └── PumpHealthMonitor.tsx
│
├── quality/
│   └── QualityRiskModel.tsx
│
└── executive/
    └── ExecutiveSummary.tsx
```

---

## 🚀 IMPLEMENTATION CHECKLIST

### Phase 1: Core Anomaly Detection (Weeks 1-2) ✅
- [x] AnomalyDetectionDashboard with all tabs
- [x] Live anomalies table
- [x] KPI cards (active, confidence, MTTR, FPR)
- [x] Severity & confidence matrix
- [x] Detail panel modal
- [x] Work order integration
- [x] Data transformation hooks
- [x] Reports tab with export

### Phase 2: Additional AI Models (Weeks 3-4) 🔄
- [x] Leak & Burst Classifier
- [x] Pump Health Monitor
- [x] Water Quality Risk Model
- [x] Executive Summary Dashboard
- [ ] Backend API integration (in progress)
- [ ] Real-time WebSocket updates
- [ ] Historical data population

### Phase 3: Advanced Features (Weeks 5-6)
- [ ] Root Cause Assistant
- [ ] Demand Forecasting
- [ ] Energy Optimization
- [ ] Mobile field app
- [ ] GPS map integration
- [ ] Advanced filtering & search

### Phase 4: Production Deployment (Weeks 7-8)
- [ ] Performance optimization
- [ ] Load testing
- [ ] Security audit
- [ ] User acceptance testing
- [ ] Production deployment
- [ ] Training & documentation

---

## 📱 HOW TO ADD TO SIDEBAR NAVIGATION

### File: `frontend/src/components/Sidebar.tsx`

Add this to your domain definition:

```typescript
{
  id: 'analytics',
  name: 'Analytics & AI',
  icon: '📊',
  subdomains: [
    { id: 'executive-summary', name: '📊 Executive Summary', tabId: 'executive' },
    { id: 'anomaly-detection', name: '🔴 Anomaly Detection', tabId: 'anomaly' },
    { id: 'leak-detection', name: '💧 Leak Detection', tabId: 'leak' },
    { id: 'pump-health', name: '🔧 Pump Health', tabId: 'pump' },
    { id: 'quality-model', name: '🧪 Water Quality', tabId: 'quality' },
    { id: 'demand-forecast', name: '📈 Demand Forecast', tabId: 'forecast' },
    { id: 'root-cause', name: '🔬 Root Cause', tabId: 'rootcause' },
    { id: 'energy-opt', name: '🎯 Energy Optimize', tabId: 'energy' },
  ],
}
```

---

## 📊 HOW TO ADD TO APP.tsx ROUTING

### File: `frontend/src/App.tsx`

Add to your routing logic:

```typescript
import {
  AnomalyDetectionDashboard,
  LeakBurstClassifier,
  PumpHealthMonitor,
  QualityRiskModel,
  ExecutiveSummary,
} from './modules/analytics/ai';

// In your tab routing:
{tab === 'executive' && <ExecutiveSummary />}
{tab === 'anomaly' && <AnomalyDetectionDashboard />}
{tab === 'leak' && <LeakBurstClassifier />}
{tab === 'pump' && <PumpHealthMonitor />}
{tab === 'quality' && <QualityRiskModel />}
```

---

## 🔌 BACKEND API ENDPOINTS REQUIRED

Each module needs these API endpoints:

### Anomaly Detection
```
GET  /api/ai/anomalies/active
GET  /api/ai/anomalies/{id}
GET  /api/ai/anomalies/history?days=30
GET  /api/ai/anomalies/metrics
POST /api/ai/anomalies/{id}/dismiss
GET  /api/ai/alert-rules
POST /api/ai/alert-rules
GET  /api/ai/sensors/health
POST /api/work-orders
```

### Leak Detection (to build)
```
GET  /api/ai/leaks/active
GET  /api/ai/leaks/history?days=30
GET  /api/ai/leaks/nrw-summary
```

### Pump Monitoring (to build)
```
GET  /api/ai/pumps
GET  /api/ai/pumps/{id}/metrics
GET  /api/ai/pumps/{id}/maintenance
POST /api/ai/pumps/{id}/schedule-maintenance
```

### Water Quality (to build)
```
GET  /api/ai/quality/parameters
GET  /api/ai/quality/compliance
GET  /api/ai/quality/parameters/{id}/trend
```

### Demand Forecasting (to build)
```
GET  /api/ai/forecast/demand/24h
GET  /api/ai/forecast/demand/trend
GET  /api/ai/forecast/accuracy
```

---

## 🎯 USER ROLES & PERMISSIONS

### Operators (View + Assign)
- View all dashboards (read-only)
- Assign work orders
- Dismiss anomalies (with reason)
- View sensor health

### Engineers (Configure)
- Configure alert rules
- Adjust thresholds
- Calibrate sensors
- Access configuration tabs

### Managers (Analyze + Report)
- View all reports
- Export data (CSV/PDF)
- Access executive summary
- Manage teams

### Admins (Full Access)
- All features
- System configuration
- User management
- Data cleanup

---

## 📈 KEY METRICS DEFINITIONS

### Anomaly Detection KPIs
- **MTTR (Mean Time To Resolve)**: Average time from detection to resolution
- **False Positive Rate**: % of flagged anomalies that were incorrect
- **Avg Confidence**: Average ML model confidence across active anomalies
- **Active Count**: Number of unresolved anomalies

### Leak Detection KPIs
- **Network Loss (NRW)**: % of water lost to leaks/theft
- **Detection Latency**: Time to identify leak after occurrence
- **Estimated Loss Rate**: m³/hour of water being lost
- **Resolution Rate**: % of leaks fixed

### Pump Health KPIs
- **Health Score**: 0-100% composite health metric
- **Efficiency**: % of theoretical max power conversion
- **Vibration**: mm/s at sensor mounting point
- **TTF (Time to Failure)**: Days until likely component failure

### Water Quality KPIs
- **Compliance Rate**: % of parameters within safe limits
- **Quality Score**: 0-100 composite quality rating
- **Parameter Trend**: Improving/stable/declining per metric
- **Calibration Age**: Days since last sensor calibration

---

## 🔄 DATA REFRESH RATES

| Component | Refresh Rate | Method |
|-----------|-------------|---------|
| Live Anomalies | Real-time | WebSocket |
| KPI Cards | 30 seconds | HTTP poll |
| Severity Matrix | 30 seconds | HTTP poll |
| History/Reports | 5 minutes | HTTP cached |
| Sensor Health | 1 minute | HTTP poll |
| Pump Metrics | Real-time | WebSocket |
| Quality Params | Real-time | WebSocket |
| Executive Summary | 30 seconds | HTTP poll |

---

## 🎨 COLOR CODING SYSTEM

### Severity Levels
- 🔴 **Critical** (9.0-10.0): #dc3545 — Immediate action required
- 🟠 **High** (7.0-9.0): #ff9800 — Address within 30 min
- 🟡 **Medium** (5.0-7.0): #0099ff — Monitor & plan
- 🟢 **Low** (<5.0): #28a745 — Low priority

### Status Indicators
- 🟢 **Healthy/Pass**: #28a745
- 🟡 **Warning/Degraded**: #ff9800
- 🔴 **Critical/Fail**: #dc3545
- ⚪ **Pending**: #ccc

### Trend Arrows
- 📈 **Improving/Up**: Green (#28a745)
- 📉 **Declining/Down**: Red (#dc3545)
- ➡️ **Stable**: Gray (var(--text2))

---

## 💡 DESIGN PRINCIPLES

1. **Real-time First**: All dashboards prioritize live data
2. **Severity-Driven**: High-risk items float to top
3. **Actionable**: Every alert includes recommended action
4. **Quantified**: All metrics show trend vs. baseline
5. **Accessible**: Color + icon + text for clarity
6. **Mobile-Ready**: Responsive grid layouts
7. **Performance**: Data caching where appropriate

---

## 📞 SUPPORT & DOCUMENTATION

- **Full Design**: See `AI_ANOMALY_DETECTION_DESIGN.md`
- **Components**: See `ANOMALY_DETECTION_COMPONENTS.md`
- **Implementation**: See `ANOMALY_DETECTION_IMPLEMENTATION.md`
- **Quick Start**: See `QUICK_START_ANOMALY_DETECTION.md`

---

**Status**: Ready for Phase 2 Backend Integration
**Last Updated**: 2026-06-04
**Version**: 1.0.0