Skip to main content

Device AI Predictions - Documentation Suite

This documentation suite provides a comprehensive design for adding AI prediction support for Device (water meter) time-series data to the Hydrotrek DWD system.

📚 Documentation Overview​

1. Main Design Document​

File: device_ai_predictions_design.md (13,000+ words)

The comprehensive design specification covering:

  • Current state analysis
  • Device data model and relationships
  • Complete architecture design
  • Backend implementation (FastAPI + ASP.NET)
  • Frontend implementation (React)
  • API contracts and data formats
  • Implementation plan with effort estimates
  • Testing strategy and considerations
  • Future enhancements

Best for: Understanding the full design, architecture decisions, and detailed specifications.

2. Quick Reference Guide​

File: device_ai_predictions_quick_reference.md (7,000+ words)

A condensed implementation guide with:

  • Key changes summary
  • Step-by-step implementation instructions
  • Code snippets and templates
  • Testing checklist
  • Troubleshooting guide
  • API examples
  • Data flow diagrams

Best for: Developers ready to implement, looking for code examples and step-by-step guidance.

3. Architecture Comparison​

File: device_ai_predictions_comparison.md (10,000+ words)

Side-by-side comparison of existing vs. proposed:

  • High-level architecture diagrams
  • Data model comparisons
  • API endpoint comparisons
  • Frontend component comparisons
  • Prediction pipeline analysis
  • Configuration differences
  • Performance characteristics

Best for: Understanding how Device predictions fit into the existing system and what's reusable.

🎯 Quick Start​

For Product Owners / Managers​

  1. Read the Executive Summary below
  2. Review the Implementation Plan section in the main design doc
  3. Check the Effort Estimates (10-14 hours total)

For Architects / Tech Leads​

  1. Start with Architecture Comparison document
  2. Review the Data Flow Diagrams in Quick Reference
  3. Read the Design Goals and Key Considerations in main design

For Developers​

  1. Start with Quick Reference Guide
  2. Copy the Code Snippets as starting templates
  3. Follow the Implementation Steps (4 phases)
  4. Use the Testing Checklist for validation

For QA / Testers​

  1. Review the Testing Strategy in main design
  2. Use the Testing Checklist in Quick Reference
  3. Reference the Troubleshooting Guide for common issues

🚀 Executive Summary​

What We're Building​

Add AI-powered forecasting for water meter consumption data, reusing the existing TSAI prediction infrastructure built for hydraulic model data.

Why It Matters​

  • Predictive Insights: Forecast future consumption patterns
  • Anomaly Detection: Identify unusual consumption early
  • Resource Planning: Better predict water demand
  • Customer Service: Proactive billing estimates

How It Works​

User → Clicks "AI Predictions" button on Device chart
     → Frontend fetches from FastAPI prediction service
     → FastAPI gets historical data from ASP.NET API
     → TSAI model generates forecasts
     → Chart displays predictions with visual distinction

What's Reusable​

  • ✅ 70-80% of existing code can be reused
  • ✅ Prediction algorithms (TSAI + scikit-learn)
  • ✅ UI components (PredictionButton)
  • ✅ UX patterns (toggle predictions on/off)
  • ✅ Configuration system

What's New​

  • ❌ ASP.NET endpoint: /api/Device/{deviceId}/tag/{tagId}/data
  • ❌ FastAPI endpoint: /device/{device_id}/tag/{tag_id}/graph-data
  • ❌ Enhanced DeviceChart component to support predictions
  • ❌ Device-specific configuration

Effort Estimate​

  • Backend (ASP.NET): 2-3 hours
  • Backend (FastAPI): 3-4 hours
  • Frontend (React): 3-4 hours
  • Testing & Polish: 2-3 hours
  • Total: 10-14 hours

Risk Level​

Low - High code reusability, well-understood patterns, limited scope.

📊 Key Metrics​

Code Reusability​

  • Prediction Logic: 100% reusable
  • UI Components: 100% reusable (PredictionButton)
  • API Patterns: 80% reusable (similar structure)
  • Chart Components: 60% reusable (needs enhancement)
  • Overall: ~70-80% reusable

Implementation Scope​

  • New Files: 0 (all enhancements to existing files)
  • Modified Files: ~5-7 files
  • Lines of Code: ~400-600 new LOC
  • API Endpoints: 2 new endpoints

Performance Expectations​

  • Training Time: < 1 second (small datasets)
  • Prediction Time: < 0.5 seconds
  • Memory Usage: < 10MB per request
  • Cache-able: Yes (data changes monthly/quarterly)

🏗️ Architecture at a Glance​

Data Flow​

┌─────────────────────────────────────────────────────────────┐
│ User Interface                                              │
│ • Clicks "AI Predictions" button on Device chart           │
│ • DeviceChart component re-renders with predictions=true   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Prediction Service (Python)                        │
│ • GET /device/{id}/tag/{tag_id}/graph-data                 │
│ • Fetches raw data from ASP.NET API                        │
│ • Applies TSAI InceptionTimePlus model                     │
│ • Returns data + predictions with isForecast flag          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ ASP.NET API (C#)                                            │
│ • GET /api/Device/{deviceId}/tag/{tagId}/data              │
│ • Queries DeviceTagDatum table                             │
│ • Returns [{ unixTime, value }, ...]                       │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ PostgreSQL Database                                         │
│ • DeviceTagDatum table                                      │
│ • Indexed on DeviceTagId, UnixTime                         │
└─────────────────────────────────────────────────────────────┘

Component Integration​

EsriCustomPopup (Existing)
   └─ PredictionButton (Existing, Reused) ✅
   └─ DeviceChart (Enhanced) ⚠️
       ├─ showPredictions prop (New) ❌
       ├─ Fetch from FastAPI if predictions=true (New) ❌
       ├─ Fetch from ASP.NET if predictions=false (Existing) ✅
       └─ Style forecast data differently (New) ❌

📋 Implementation Checklist​

Phase 1: Backend (ASP.NET) - 2-3 hours​

  • Add GetDeviceTagData endpoint to DeviceController.cs
  • Add GetDeviceTagInfo endpoint to DeviceController.cs
  • Add request/response DTOs
  • Test endpoints with Postman
  • Verify data format matches design

Phase 2: Backend (FastAPI) - 3-4 hours​

  • Add DeviceTagData Pydantic model to main.py
  • Add DeviceTagInfo Pydantic model to main.py
  • Add get_device_tag_graph_data endpoint to main.py
  • Add DEVICE_CONFIG to config.py
  • Test with sample device data
  • Verify predictions are generated correctly

Phase 3: Frontend (React) - 3-4 hours​

  • Modify DeviceChart.jsx to accept showPredictions prop
  • Add conditional API fetching logic (FastAPI vs ASP.NET)
  • Add forecast data styling (dashed line, opacity)
  • Update EsriCustomPopup.jsx to include PredictionButton
  • Pass showPredictions state to DeviceChart
  • Add FASTAPI_ENDPOINTS.GetDeviceTagGraphData to constants
  • Test in browser with real data

Phase 4: Testing & Polish - 2-3 hours​

  • End-to-end testing with various device types
  • Test with different tag types (monthly, quarterly, yearly)
  • Test with sparse data (< 10 points)
  • Test error handling and edge cases
  • Performance testing with large datasets
  • UI/UX refinement
  • Update documentation

🧪 Testing Scenarios​

Functional Tests​

  1. ✅ Predictions work for monthly consumption data
  2. ✅ Predictions work for quarterly consumption data
  3. ✅ Predictions work for yearly consumption data
  4. ✅ Toggle predictions on/off works correctly
  5. ✅ Chart styling distinguishes historical vs. forecast
  6. ✅ Loading states display correctly
  7. ✅ Error handling works (404, 500, etc.)
  8. ✅ Works with single tag (one axis)
  9. ✅ Works with dual tags (two axes)

Edge Cases​

  1. ⚠️ Device with no data (empty result)
  2. ⚠️ Device with only 1-2 data points (below minimum)
  3. ⚠️ Device with gaps in data (missing months)
  4. ⚠️ Device with anomalous data (spikes, zeros)
  5. ⚠️ Very large datasets (> 100 points)
  6. ⚠️ Invalid device ID (404 response)
  7. ⚠️ Invalid tag ID (404 response)

Performance Tests​

  1. 🚀 Response time < 2 seconds
  2. 🚀 Memory usage reasonable (< 50MB)
  3. 🚀 Concurrent requests handled correctly
  4. 🚀 Large datasets (1000+ points) handled efficiently

🐛 Troubleshooting Guide​

Issue: Predictions Not Showing​

Symptoms: Button toggles but chart doesn't update

Debug Steps:

  1. Check browser console for errors
  2. Verify showPredictions prop is being passed
  3. Check FastAPI endpoint is responding (Network tab)
  4. Verify isForecast flag is present in response
  5. Check chart data transformation logic

Issue: 404 from ASP.NET API​

Symptoms: Error message "Device not found"

Debug Steps:

  1. Verify device exists in database
  2. Verify tag exists and belongs to device
  3. Check DeviceTagId foreign key relationship
  4. Test endpoint directly in Postman

Issue: Poor Prediction Quality​

Symptoms: Predictions look unrealistic

Root Causes:

  • Insufficient data (< 10 points)
  • High data variance (seasonal spikes)
  • Anomalous data (errors in readings)

Solutions:

  • Increase minimum data points threshold
  • Use simpler fallback model (moving average)
  • Clean data before prediction
  • Adjust forecast percentage (lower = more conservative)

Issue: Slow Performance​

Symptoms: Predictions take > 5 seconds

Debug Steps:

  1. Check data volume (how many points?)
  2. Add date range filters to limit data
  3. Check database indexes on UnixTime
  4. Consider caching predictions
  5. Profile FastAPI with timing logs

📚 Additional Resources​

  • Azure Configuration: azure_configuration_quick_reference.md
  • Blob Storage: blob_storage_phases_1-4_complete.md
  • Database Schema: See efcorelibraries/EN2PostgresContext

Code References​

  • Existing Predictions: dwd-api-fastapi/main.py (lines 532-662)
  • Prediction Button: dwd-frontend-react/src/components/PredictionButton.jsx
  • Forecast Chart Example: dwd-frontend-react/src/components/ForecastChart.jsx
  • Device Controller: dwd-api-aspnet/DwdApiAspNet/Controllers/DeviceController.cs
  • Device Chart: dwd-frontend-react/src/components/DeviceChart.jsx

External Resources​

🔄 Revision History​

DateVersionAuthorChanges
2025-10-231.0AI AssistantInitial design documentation suite created

📧 Contact & Support​

For questions or clarifications about this design:

  1. Review the three design documents in order
  2. Check the troubleshooting guide
  3. Reference existing code examples
  4. Consult with the development team

✅ Next Steps​

  1. Review all three design documents
  2. Discuss with team (architects, developers, QA)
  3. Estimate effort and schedule implementation
  4. Implement following the 4-phase plan
  5. Test thoroughly using provided checklists
  6. Deploy to staging environment first
  7. Monitor performance and user feedback
  8. Iterate based on results

🎉 Expected Outcomes​

Upon successful implementation, users will be able to:

✅ View AI predictions for any device's consumption data ✅ Toggle predictions on/off with a single button click ✅ See forecast data visually distinguished from historical data ✅ Get reliable forecasts using industry-standard ML algorithms (TSAI) ✅ Experience consistent UX with existing prediction features ✅ Benefit from fast performance (< 2 second response times)

This will provide valuable insights for:

  • Water utility planners
  • Operations teams
  • Customer service representatives
  • Data analysts
  • Customers (future potential)

📄 Document Index​

DocumentPurposeLengthAudience
Main DesignComplete specification13,000+ wordsArchitects, PMs
Quick ReferenceImplementation guide7,000+ wordsDevelopers, QA
ComparisonArchitecture analysis10,000+ wordsArchitects, Tech Leads
This READMEOverview & navigation2,500+ wordsEveryone

Total Documentation: ~32,500 words / ~65 pages

Last Updated: October 23, 2025

Last updated on by Jake, Cursor