Platform (Backend/API) Roadmap

This document outlines the roadmap for the Voltimax Platform API and backend services.

Reference: src/Voltimax.Platform.Api/, src/Voltimax.Platform.Data/, src/Voltimax.Platform.Functions/

Architecture:

• ASP.NET Core Minimal APIs with endpoint groups
• Scalar for OpenAPI documentation UI
• Mediator pattern (source-generated) for CQRS
• FluentValidation for request validation
• PostgreSQL with TimescaleDB + Elasticsearch dual storage
• EF Core 10.0.1 with 14 completed migrations

---

Phase P1: API Stabilization

Task	Status	Priority	Description
Audit logging	❌ Not Started	High	EF Core interceptors to log all CUD operations to audit table

Success Criteria:

• All EF Core entities have audit interceptors
• Audit logs queryable via Elasticsearch
• Audit viewer in admin UI can filter by user, entity, date

Dependencies:

• None (can start immediately)

Implementation Status:

Completed:

• ✅ Core REST API with 40+ endpoints:
  • Locations, Assets, Batteries, Solar Panels, Grid Connections
  • Pricing (day-ahead, intraday)
  • Solar Forecasts, Workflows, Metrics
• ✅ Entity Framework Core data access layer
• ✅ PostgreSQL database with TimescaleDB optimizations
• ✅ CQRS with Mediator pattern (source-generated)
• ✅ FluentValidation for request validation
• ✅ Keycloak integration (JWT auth, role-based permissions)
• ✅ OpenAPI/Scalar documentation

Not Started:

• ❌ EF Core audit interceptors (no SaveChangesInterceptor implementation)
• ❌ Audit log entities in database schema
• ❌ Audit repository or queries
• ❌ Audit trail UI (depends on F4)

Implementation notes:

• Audit logs should include user ID, timestamp, entity type, old/new values
• Audit interceptor should use SaveChangesInterceptor pattern
• API versioning, rate limiting, and webhooks deferred until production requirements emerge

Related ADRs:

• ADR-002: Deferred API versioning for greenfield velocity
• ADR-004: Elasticsearch for audit log storage and search

---

Phase P2: Data Services & Analytics

Reference: src/Voltimax.Platform.Functions/, src/Voltimax.Iot.Metrics/, src/Voltimax.EnergyAdvisor/

Task	Status	Priority	Description
Anomaly detection service	❌ Not Started	Medium	Statistical anomaly detection (Z-score, IQR) on metrics streams
Energy consumption forecasting	⚠️ Partial	Medium	Time-series forecasting using historical patterns + weather data
Data export API	❌ Not Started	Medium	Async bulk export with pagination, supports CSV/JSON/Parquet

Success Criteria:

• Anomaly detection catches 95%+ of known anomaly patterns in test data
• Forecasting accuracy within 15% MAPE for 24-hour ahead predictions
• Export API handles 1M+ data points without timeout

Dependencies:

• Requires sufficient historical data (3+ months for forecasting)

Implementation Status:

Completed:

• ✅ Azure Functions pipeline:
  • DayAheadPricingFunction - Timer trigger daily at 13:30 UTC
  • IntraDayPricingFunction - Timer trigger hourly at :05
  • TelemetryFunction - Service Bus trigger for telemetry ingestion
• ✅ Metrics infrastructure (Voltimax.Iot.Metrics):
  • 20+ query handlers for metrics analysis
  • Real-time asset summaries
  • Historical statistics and aggregations
  • Rate calculations for cumulative metrics
  • Histogram/time-series buckets
  • Cross-asset aggregations
  • Health status checks
  • Metric coverage analysis
  • Ingestion rate monitoring
• ✅ Pricing services:
  • PriceFetchService (ENTSO-E integration)
  • PriceStorageService (PostgreSQL persistence)
• ✅ Solar forecast integration:
  • Quartz Solar API client
  • PVGIS API integration
  • Forecast data storage

In Progress:

• ⚠️ Energy forecasting - Placeholder only (ForecastService.cs):
  • Interface and DI setup complete
  • Returns empty forecast data
  • Missing: Actual Forecast.Solar API integration or ML model

Not Started:

• ❌ Anomaly detection: No statistical analysis implementation
  • No Z-score calculation
  • No IQR-based outlier detection
  • No baseline models
  • No alerting mechanism
• ❌ Data export API:
  • No CSV/JSON/Parquet export endpoints
  • No bulk download capability
  • No file generation services
  • No scheduled export jobs

Implementation notes:

• Telemetry ingestion via Azure Service Bus queue with dead-letter handling
• Elastic APM integration for distributed tracing
• PostgreSQL for pricing data storage, Elasticsearch for time-series metrics
• Ad-hoc queries in Elasticsearch sufficient for current needs, scheduled reports deferred
• Metrics system is production-ready for querying, but lacks advanced analytics

Related ADRs:

• ADR-003: Elasticsearch over TimescaleDB for time-series data

---

Phase P3: External Integrations

Reference: src/Voltimax.Entsoe/, src/Voltimax.PvGis/

Task	Status	Priority	Description
EPEX Spot pricing (ENTSO-E)	✅ Complete	-	Day-ahead and intraday electricity pricing via ENTSO-E API
Solar forecasting APIs	✅ Complete	-	PVGIS and Quartz Solar API integration
Energy provider APIs	❌ Not Started	Medium	Grid operator data feeds (capacity, constraints, curtailment signals)
Carbon tracking service	❌ Not Started	Low	Real-time grid carbon intensity from electricityMap or similar
Home Assistant bridge	❌ Not Started	Medium	REST API + WebSocket bridge for HA integration
Homey integration	❌ Not Started	High	Homey Web API + WebSocket for device control and automation
IEC 61850 support	❌ Not Started	Low	MMS/GOOSE for utility substation integration
IEC 62056 (DLMS/COSEM)	❌ Not Started	Low	Smart meter data exchange protocol

Success Criteria:

• HA bridge supports 20+ device types with bidirectional control
• Homey integration exposes battery, inverter, and EV charger devices to Homey flows
• IEC protocols pass conformance testing where applicable
• Carbon intensity data updates every 15 minutes with <5% gaps

Dependencies:

• IEC 61850 blocked by library licensing/cost evaluation (€10k-50k)
• Carbon tracking requires third-party API selection
• Homey integration requires Gateway bidirectional communication (G3)

Implementation Status:

Completed:

• ✅ ENTSO-E/EPEX Spot pricing (src/Voltimax.Entsoe/):
  • EpexQueryService - ENTSO-E API client
  • EntsoeEpexDeserializer - XML parsing
  • PriceRequestResponseFormatter - Protocol formatting
  • API endpoints:
    • GET /api/pricing/day-ahead/{biddingZone} (with date ranges)
    • GET /api/pricing/day-ahead/{biddingZone}/today
    • GET /api/pricing/day-ahead/{biddingZone}/tomorrow
    • GET /api/pricing/intraday/{biddingZone} (with date ranges)
    • GET /api/pricing/intraday/{biddingZone}/today
    • GET /api/pricing/intraday/{biddingZone}/tomorrow
  • Database entities: DayAheadPrice, IntraDayPrice, BiddingZone
  • Azure Functions for scheduled fetching
• ✅ Solar forecasting (src/Voltimax.PvGis/, src/Voltimax.EnergyAdvisor/):
  • PVGIS API integration
  • Quartz Solar API client
  • POST /api/solar-forecast/ endpoint
  • Forecast data persistence

Not Started:

• ❌ Additional energy provider APIs (grid capacity, curtailment signals)
• ❌ Carbon tracking service (no CO2/emissions tracking)
• ❌ Home Assistant bridge (no MQTT/REST bridge)
• ❌ Homey integration (no Homey API client)
• ❌ IEC 61850 (no GOOSE/MMS protocols)
• ❌ IEC 62056 (DLMS/COSEM) (no smart meter protocols)

Implementation notes:

• EPEX Spot pricing integration complete and operational
• PVGIS and Quartz Solar forecasting operational
• Homey Web API v3.0+ with local/cloud API support (when implemented)
• Homey devices exposed as battery, solar, grid metrics in flows (when implemented)
• Additional energy provider integrations country-specific (DE, NL, BE)
• Other relevant standards for reference: IEC 61968/61970 (CIM), IEC 62351 (security), IEC 60870-5-104 (SCADA)

Known Risks:

• IEC 61850 certified library expensive (€10k-50k), may limit adoption
• DLMS/COSEM smart meter protocols fragmented by vendor
• Carbon intensity APIs may have rate limits or require paid plans
• Homey local API requires network discovery, cloud API requires OAuth token management
• Home Assistant integration requires MQTT broker setup

---

Dependencies

Platform > Frontend Dependencies

Frontend Phase	Depends On	Rationale
F1 (Energy Advisory UI)	P2 (Energy consumption forecasting)	Dashboard requires forecasting data for optimization views
F1 (Price-based optimization)	P3 (EPEX pricing - completed)	Requires day-ahead and intraday pricing data
F3 (Gateway Management UI)	G3 (Configuration sync)	UI needs backend API for pushing config changes
F4 (Audit log viewer)	P1 (Audit logging)	Requires audit data to be captured and queryable

Platform > Gateway Dependencies

Gateway Phase	Depends On	Rationale
G1 (TimeOfUseStrategy)	P3 (Tariff configuration API - not yet implemented)	Strategy needs tariff schedules for optimization
G1 (ArbitrageStrategy)	P3 (EPEX pricing - completed)	Requires real-time spot market prices
G3 (Bidirectional communication)	P1 (Platform API command endpoints - not yet implemented)	API must expose gateway command endpoints
G3 (Configuration sync)	P1 (Audit logging)	Config changes must be audited for compliance

External Dependencies

Phase	External Blocker	Impact
P3 (IEC 61850 support)	Library licensing decision (€10k-50k)	Blocks utility substation integration
P3 (Carbon tracking)	Third-party API selection	Delays grid carbon intensity features
P2 (Energy forecasting)	Historical data accumulation (3+ months)	Cannot validate accuracy until sufficient data exists