01
Architecture & Patterns
3 docs
The conceptual model and the design conventions every contributor needs in their head — entity
relationships, storage tiers, EF Core patterns, and how data moves through the system.
Domain model
Energy assets, grid connections, market roles. Physical view vs. market view, BDEW/VDE-FNN alignment, the socket vs. plug distinction.
domain-model.html→
Development patterns
Storage tiers, API conventions, EF Core unit-of-work, background pipelines, time zones, DST, kick-notifiers — and the canonical recipes.
patterns.html→
Data flow
End-to-end picture of how telemetry, forecasts, schedules, and trades flow through the stack — from device to TSO and back.
data-flow.html→
02
Telemetry & Forecasting
4 docs
The time-series pipeline: how raw samples become 15-minute billing-grade aggregates, how forecasts
are derived per resource and aggregated to balance groups, and how forecasts become schedules sent
to the TSO.
Telemetry storage
Postgres-partitioned TelemetryRaw / Telemetry15m tables, bitemporal forecast archive, retention.
telemetry.html→
Telemetry processing
The pipeline coordinator, downsampling stages, derived series, and the dependency graph between background services.
telemetry-processing.html→
Forecasting
Bottom-up forecast hierarchy: resource → MaLo (billing) → balance group. SLP synthesis, physical vs. billing tracks.
forecast.html→
Consumption forecast baseline
Day-type averaging beats the SLP forecast on every prod site (−53 % MAE): the decision, the evidence, and the baseline future forecasts must beat.
forecast-consumption-baseline.html→
Schedule lifecycle
From approved forecast to the 4× daily Fahrplan submission. Draft / Created / Sent states, send-gating, and trade interlock.
schedule.html→
03
Trading & Markets
8 docs
Day-ahead trading, balancing, and market communication (MaKo). How OKE participates in the German
energy market via VICOS, balance-group management, and the EDIFACT message exchanges.
Trade lifecycle
Trade state machine, request / confirm / settled flow, integration with schedule send-gating.
trade.html→
Trading interface
Operator UI for placing trades, inspecting flows, and reconciling positions against schedules.
trading-interface.html→
Bährbots contract v0.1
External trading partner contract spec — message envelope, signature, retries, error model.
trading-baehrbots-contract-v0.1.html→
Market communication (MaKo / VICOS)
VICOS integration, inbound/outbound message routing, certificate handling, the receive-first/process-async pattern.
maco.html→
MSCONS lifecycle & supersession
How inbound MSCONS documents are kept as immutable history, classified into effective/superseded/retry/review, and gated before contributing values.
mscons.html→
Market partners
Marktpartner directory and role assignments — TSO, DSO, MSB, supplier — and how they map to OKE entities.
market-partners.html→
Invoice specification
Invoice generation flow, line items, tax handling, and the INVOIC EDIFACT export contract.
invoice.html→
Electricity tax (Stromsteuer)
MSCONS-only MaLo quantity determination, annual validation against the HZA reference, two-directional 10 % compliance monitoring + annual-forecast deadline alerts, and the Belegheft.
electricity-tax.html→
Missing day-ahead ANO workaround
Operational workaround for missing announcements from market counterparties — when to apply it and what gets reconciled later.
missing-day-ahead-ano-workaround.html→
04
EDIFACT
9 docs
Message-format references for the German energy market. One overview, an architecture page for the
parsing pipeline, and a per-message-type page (UTILMD, MSCONS, INVOIC, …) describing the AHB
mapping that OKE implements.
05
MQTT & Devices
8 docs
The device side: how Okesp gateways and the API talk over MQTT/mTLS, how gateway configurations are
pushed and rolled back, the OTA pipeline, and the control-schedule mechanism for actuating real
hardware.
MQTT & device integration
Broker topology, the EMQX / AWS IoT split, topic hierarchy, and how devices register and report online status.
mqtt.html→
V1 device protocol
The wire format spoken between Okesp gateways and the API — telemetry, status, ACKs, and version negotiation.
mqtt-protocol.html→
Device control
Control schedules — how the API actuates devices for curtailment, charging, EVU-Sperre, and the ACK lifecycle.
mqtt-control.html→
OCPP charging stations
EV chargers over OCPP 1.6J / 2.0.1 WebSockets — embedded CSMS, Redis-backed presence & command routing for multi-instance, sessions, and live control.
ocpp.html→
Heating rod control
Hardware evaluation for optimizer-controlled DHW heating rods — Shelly Pro 4PM default via local RPC, contactor variants for the ≥12 kW class, stepless diverters.
heating-rod-control.html→
Gateway configuration
JSON config schema pushed to Okesp via MQTT, persisted to LittleFS. Versioning, partial pushes, and rollbacks.
gateway-config.html→
Gateway OTA
Over-the-air firmware updates for ESP32-S3 gateways — image signing, rollout cohorts, A/B partitions, rollback.
gateway-ota.html→
Alerts
Device and platform alerts — what fires, what's surfaced to operators, and the issue-tracking integration.
alerts.html→
06
Operations
9 docs
Auth, CI/CD, observability, validation, and the cross-cutting concerns that keep the lights on.
Plus follow-up items that don't yet warrant a multi-PR plan.
Authentication
Microsoft OAuth + cookie sessions, the SuperAdmin policy, and the dev-auth bypass for CLI work.
oauth.html→
Customer portal
The read-only /portal area: one app/two shells, the token-scoped /api/portal/* surface, subscribe-time hub ownership, and the layered tenant isolation.
customer-portal.html→
CI/CD
The build/test/deploy pipeline — format, lint, test, Pulumi, image promotion, and rollback hooks.
cicd.html→
Observability (SigNoz)
Logs, metrics, and traces — what to instrument, how to query SigNoz, and the conventions for span names.
observability.html→
Validation & issues
Cross-entity validation, the site-issues service, and how operator-facing validation problems are surfaced.
validation.html→
Site optimization
Site-level optimization service — what it considers, its outputs, and how it interacts with control schedules.
optimization.html→
Maps & map tiles
Tile provider configuration, attribution, and the customer/site map experience.
maps.html→
E2E testing (Playwright)
Quick-start, env vars, where tests live, and how to debug them locally.
e2e-testing.html→
Customer audit log
What gets audited, retention, and the operator query surface.
customer-audit-log.html→
Follow-up items
Cross-cutting TODOs too small for a plan doc — control overrides, schedule enforcement gaps, EFS cleanup.
todo.html→