# Anomaly Detection Dashboard - Implementation Guide

## Overview

This document provides complete implementation instructions for integrating the AI Anomaly Detection Dashboard into the IC³ Platform.

## Project Structure

```
frontend/src/modules/analytics/ai/anomaly/
├── AnomalyDetectionDashboard.tsx          # Main component
├── components/
│   ├── AnomalyKPICards.tsx               # KPI metrics cards
│   ├── AnomalyTable.tsx                  # Live anomalies list
│   ├── AnomalyDetailPanel.tsx            # Detail modal
│   ├── SeverityMatrix.tsx                # Distribution charts
│   ├── AnomalyHistoryTab.tsx             # 30-day trends
│   ├── AlertRulesConfig.tsx              # Alert rule editor
│   └── SensorHealthScorecard.tsx         # Sensor trust scores
├── services/
│   └── anomalyService.ts                 # API client
├── hooks/
│   └── useAnomalyDetection.ts            # React hooks
├── types.ts                              # TypeScript interfaces
├── styles/
│   └── anomalyDetection.module.css       # Component styles
└── index.ts                              # Module exports

backend/src/routes/
└── anomalyDetection.ts                   # API endpoints

backend/database/migrations/
└── create_anomaly_tables.sql             # Database schema
```

## Installation Steps

### 1. Frontend Setup

#### 1.1 Install Dependencies

The anomaly detection module uses React and TypeScript (already installed in IC³).

```bash
cd frontend
npm install
```

#### 1.2 Add Routes to Main App

Edit `frontend/src/App.tsx`:

```typescript
import { AnomalyDetectionDashboard } from './modules/analytics/ai/anomaly';

// Add to your domain routing:
const domainPanels: Record<string, React.FC<any>> = {
  // ... existing panels ...
  'anomaly-detection': AnomalyDetectionDashboard,
};
```

#### 1.3 Add to Sidebar Navigation

Edit `frontend/src/components/Sidebar.tsx`:

```typescript
const aiModules = [
  { id: 'anomaly-detection', label: '🔴 Anomaly Detection', icon: '📊' },
  { id: 'leak-classifier', label: '💧 Leak/Burst Detection', icon: '💧' },
  { id: 'pump-health', label: '⚙️ Pump Health', icon: '⚙️' },
  // ... other AI modules
];
```

### 2. Backend Setup

#### 2.1 Database Setup

Run the migration to create necessary tables:

```bash
# Using psql
psql -U postgres -d ic3_database -f backend/database/migrations/create_anomaly_tables.sql

# Or via your migration tool:
npm run migrate
```

#### 2.2 API Routes Integration

Edit `backend/src/app.ts` or `server.ts`:

```typescript
import anomalyRoutes from './routes/anomalyDetection';

// Mount routes
app.use('/api/ai/anomalies', anomalyRoutes);
```

#### 2.3 Environment Variables

Add to `.env`:

```
VITE_API_URL=http://localhost:3001
VITE_ANOMALY_API=http://localhost:3001/api/ai

# Database
DB_ANOMALY_TABLE=ic3_anomalies
DB_AUDIT_TABLE=ic3_anomaly_audit_trail
DB_RULES_TABLE=ic3_alert_rules
DB_SENSORS_TABLE=ic3_sensor_health
```

### 3. Real-Time Integration (WebSocket)

#### 3.1 Setup WebSocket Handler

Edit `backend/src/websocket/handlers.ts`:

```typescript
import { AnomalyService } from '../services/anomalyDetection';

export const setupAnomalyWebSocket = (ws, userId) => {
  // Subscribe to active anomalies
  ws.on('subscribe:anomalies', async () => {
    const active = await AnomalyService.getActiveAnomalies();
    ws.emit('anomalies:update', active);
  });

  // Poll every 30 seconds
  const interval = setInterval(async () => {
    const active = await AnomalyService.getActiveAnomalies();
    ws.emit('anomalies:update', active);
  }, 30000);

  ws.on('disconnect', () => clearInterval(interval));
};
```

#### 3.2 Update Frontend Hook

The `useAnomalyDetection` hook supports WebSocket in addition to HTTP polling:

```typescript
// Optional: Use WebSocket instead of polling
const setupWebSocket = () => {
  const ws = new WebSocket(`ws://localhost:3001`);
  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'anomalies:update') {
      setAnomalies(data.payload);
    }
  };
};
```

## API Endpoints

### Anomalies

```
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/anomalies/export?format=csv&startDate=...&endDate=...
```

### Alert Rules

```
GET    /api/ai/alert-rules
POST   /api/ai/alert-rules
PUT    /api/ai/alert-rules/:id
DELETE /api/ai/alert-rules/:id
```

### Sensor Health

```
GET    /api/ai/sensors/health
```

## Data Flow

### 1. Anomaly Detection Pipeline

```
Field Sensors
  ↓
Data Ingestion (SCADA/IoT/HES)
  ↓
Sensor Trust Engine
  ↓
AI Anomaly Detection Models (8 models)
  ↓
Severity Scoring & Confidence Calculation
  ↓
Database Storage
  ↓
Real-time Push to Dashboard
  ↓
Work Order Generation (Optional)
```

### 2. Dashboard Update Cycle

```
Frontend (React)
  ↓
useAnomalyDetection Hook (30s polling)
  ↓
AnomalyService (HTTP API calls)
  ↓
Backend Routes
  ↓
Database Queries
  ↓
Response → Dashboard Update
```

## Configuration

### 1. Alert Rules

Configure per sensor type:

```typescript
{
  sensorType: 'flow_meter',
  threshold: {
    percentageDeviation: 25  // Alert if ±25%
  },
  severity: 'high'
}
```

### 2. Severity Thresholds

```typescript
SEVERITY_CRITICAL = 9.0   // Immediate action
SEVERITY_HIGH = 7.0       // Address within 30 min
SEVERITY_MEDIUM = 5.0     // Monitor & plan
SEVERITY_LOW < 5.0        // Log only
```

### 3. Confidence Levels

```
✓✓ Excellent: >90%   (trustworthy output)
✓  Good:      70-90% (acceptable)
⚠  Fair:      50-70% (requires validation)
❌ Poor:      <50%   (likely false positive)
```

## Testing

### Unit Tests

```bash
# Frontend components
npm run test -- frontend/src/modules/analytics/ai/anomaly

# Backend routes
npm run test -- backend/src/routes/anomalyDetection.ts
```

### Integration Tests

```bash
# Full API flow
npm run test:integration
```

### E2E Tests

```bash
# Dashboard functionality
npm run test:e2e -- anomaly-detection
```

## Sample Data Seeding

To seed sample anomalies for testing:

```bash
npm run seed:anomalies
```

File: `backend/database/seeds/anomalies.seed.ts`

```typescript
import { AnomalyService } from '../services/anomalyDetection';

export const seedAnomalies = async () => {
  const anomalies = [
    {
      assetId: 'DMA-05',
      assetName: 'Flow Meter DMA-05',
      severity: 9.2,
      confidence: 94,
      // ... complete anomaly object
    },
    // ... more samples
  ];

  for (const anomaly of anomalies) {
    await AnomalyService.createAnomaly(anomaly);
  }
};
```

## Performance Optimization

### 1. Database Indexing

All critical queries have indexes:
- `idx_anomalies_status` - Status filtering
- `idx_anomalies_severity` - Severity sorting
- `idx_anomalies_detected_at` - Time-based queries
- `idx_sensor_health_trust_score` - Trust scoring

### 2. Caching Strategy

```typescript
// Cache active anomalies for 30 seconds
const ANOMALY_CACHE_TTL = 30000;

export const getActiveAnomalies = memoize(
  async () => AnomalyService.getActiveAnomalies(),
  { maxAge: ANOMALY_CACHE_TTL }
);
```

### 3. Virtual Scrolling

For large anomaly lists, implement virtual scrolling:

```typescript
import { FixedSizeList } from 'react-window';

<FixedSizeList
  height={600}
  itemCount={anomalies.length}
  itemSize={60}
>
  {Row}
</FixedSizeList>
```

## Monitoring & Debugging

### 1. Logging

```typescript
// Enable debug logging
export const DEBUG = process.env.VITE_DEBUG === 'true';

if (DEBUG) {
  console.log('[Anomaly Detection]', 'Fetching active anomalies...');
}
```

### 2. Performance Metrics

Monitor in browser DevTools:

```typescript
performance.mark('anomaly-fetch-start');
const anomalies = await AnomalyService.getActiveAnomalies();
performance.mark('anomaly-fetch-end');
performance.measure('anomaly-fetch', 'anomaly-fetch-start', 'anomaly-fetch-end');
```

### 3. Error Tracking

```typescript
try {
  const data = await AnomalyService.getActiveAnomalies();
  setAnomalies(data);
} catch (err) {
  console.error('[Anomaly Detection] Error:', err);
  // Send to error tracking service (Sentry, DataDog, etc.)
  errorTracker.captureException(err);
  setError(err.message);
}
```

## Security Considerations

### 1. API Authentication

All endpoints require authentication:

```typescript
// Backend middleware
app.use('/api/ai/anomalies', authenticate, authorize(['read:anomalies']));
```

### 2. Data Validation

Validate all inputs:

```typescript
const alertRuleSchema = yup.object({
  sensorType: yup.string().required(),
  severity: yup.string().oneOf(['low', 'medium', 'high', 'critical']),
});
```

### 3. Audit Trail

All actions are logged:

```typescript
anomaly.auditTrail.push({
  timestamp: new Date(),
  action: 'dismiss',
  actor: { userId: currentUser.id, name: currentUser.name, role: currentUser.role },
  details: `Dismissed: ${reason}`,
});
```

## Deployment

### 1. Production Checklist

- [ ] Database migrations applied
- [ ] API routes mounted and tested
- [ ] Frontend component built and optimized
- [ ] Environment variables configured
- [ ] WebSocket connection established (if using)
- [ ] Error tracking configured
- [ ] Monitoring dashboards set up
- [ ] Load testing completed

### 2. Docker Deployment

```dockerfile
# backend/Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci --only=production
RUN npm run migrate
CMD ["npm", "start"]
```

### 3. Kubernetes Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ic3-anomaly-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ic3-anomaly-api
  template:
    metadata:
      labels:
        app: ic3-anomaly-api
    spec:
      containers:
      - name: api
        image: ic3/anomaly-api:latest
        ports:
        - containerPort: 3001
        env:
        - name: DB_HOST
          valueFrom:
            configMapKeyRef:
              name: ic3-config
              key: db_host
```

## Troubleshooting

### Issue: Anomalies not displaying

1. Check API endpoint is responding:
   ```bash
   curl http://localhost:3001/api/ai/anomalies/active
   ```

2. Verify database connection:
   ```bash
   psql -U postgres -d ic3_database -c "SELECT COUNT(*) FROM ic3_anomalies;"
   ```

3. Check browser console for errors

### Issue: Slow performance

1. Check database query performance:
   ```sql
   EXPLAIN ANALYZE SELECT * FROM ic3_anomalies WHERE status = 'active';
   ```

2. Verify indexes exist:
   ```sql
   \d ic3_anomalies
   ```

3. Enable caching for frequent queries

### Issue: Real-time updates not working

1. Verify WebSocket connection:
   ```javascript
   const ws = new WebSocket('ws://localhost:3001');
   ws.onopen = () => console.log('Connected');
   ```

2. Check for CORS issues in headers
3. Verify port forwarding if behind proxy

## Support & Resources

- **Documentation**: See `AI_ANOMALY_DETECTION_DESIGN.md`
- **Components**: See `ANOMALY_DETECTION_COMPONENTS.md`
- **API Docs**: OpenAPI spec at `/api/docs`
- **Issues**: GitHub Issues with label `anomaly-detection`

## Next Steps

1. **Phase 1 (Weeks 1-2)**: Deploy core monitoring & dashboarding
2. **Phase 2 (Weeks 3-4)**: Add predictive maintenance & optimization models
3. **Phase 3 (Weeks 5-6)**: Integrate with work order system & mobile field app
4. **Phase 4 (Weeks 7-8)**: Advanced reporting & executive dashboards

## Version History

- **v1.0.0** (June 2026): Initial release
  - Core anomaly detection
  - 8 AI models
  - Real-time dashboard
  - Alert rules configuration
  - Sensor health monitoring