VoltWeave coordinates simulated batteries and distributed energy resources as a single virtual power plant. It covers the complete operational loop: collect live telemetry, calculate flexibility, plan and execute dispatches, measure delivery, then settle customer rewards.
The V1 release runs locally without physical hardware, an electricity-market account or a payment provider.
- Manages organizations, memberships, sites, devices and virtual power plants.
- Provisions revocable, device-scoped MQTT credentials.
- Validates, deduplicates and stores time-series telemetry.
- Maintains a durable latest-state device twin.
- Produces versioned forecast baselines and flexibility snapshots.
- Creates deterministic, explainable allocation previews.
- Runs manual and policy-controlled dispatch workflows.
- Tracks command acknowledgement, delivery and under-performance recovery.
- Creates immutable settlements and append-only reward ledger entries.
- Exposes customer, operator and administrator web journeys.
- A customer registers a site and provisions an energy device.
- The simulator publishes authenticated telemetry through MQTT.
- VoltWeave builds a durable device twin and calculates available flexibility.
- An operator reviews an allocation and confirms a dispatch.
- The platform sends commands, measures actual delivery and recovers from under-performance.
- A completed dispatch produces an immutable settlement and customer reward.
- Docker Desktop or Docker Engine with Compose
- PowerShell 7+
- At least 8 GB of memory available to Docker
- Java 21 only for local Maven tests or the standalone simulator
- Node.js 24 only for local frontend development
git clone https://github.com/Miniks040506/voltweave.git
cd voltweave
Copy-Item infrastructure/compose/.env.example infrastructure/compose/.envReplace every local-*-change-me value in the private .env, then run:
.\infrastructure\compose\release.ps1The release script:
- validates the Compose model;
- builds seven application images;
- starts the dependency graph and waits for health checks;
- checks Web and Gateway health;
- verifies anonymous requests receive
401; - obtains a real Keycloak token;
- calls an authenticated API through Gateway.
Successful startup ends with:
PASS web HTTP status
PASS gateway health
PASS anonymous API rejection
PASS customer token
PASS authenticated Gateway route
Open http://localhost:3000. The local users are
customer, operator and admin; passwords are configured in .env.
Create a fresh customer organization, operator organization, site, battery and VPP:
.\infrastructure\compose\demo.ps1Build and run the deterministic device simulator:
.\mvnw.cmd -pl simulator/simulation-service -am -DskipTests package
java -jar simulator/simulation-service/target/simulation-service-0.1.0-SNAPSHOT-exec.jar `
simulator/simulation-service/scenario.local.jsonKeep the simulator running while testing telemetry and dispatch. The generated
scenario.local.json contains a one-time MQTT credential and is ignored by Git.
Follow the V1 demo walkthrough to inspect the customer, operator and administrator journeys. It includes the expected evidence for telemetry, optimization, dispatch, settlement and audit behavior.
| Component | Local URL | Intended use |
|---|---|---|
| Web | http://localhost:3000 |
Product interface |
| API Gateway | http://localhost:8080 |
Public API boundary |
| Keycloak | http://localhost:8180 |
Local identity provider |
| Portfolio | http://localhost:8081 |
Local diagnostics only |
| Telemetry | http://localhost:8082 |
Local diagnostics only |
| Intelligence | http://localhost:8083 |
Local diagnostics only |
| Dispatch | http://localhost:8084 |
Local diagnostics only |
| Settlement | http://localhost:8085 |
Local diagnostics only |
| Prometheus | http://localhost:9090 |
Optional metrics profile |
| Grafana | http://localhost:3001 |
Optional acceptance dashboard |
Application clients should use Gateway rather than direct service ports.
| Component | Responsibility |
|---|---|
| Web | Customer, operator and administrator interfaces |
| API Gateway | Public routing, JWT validation and correlation IDs |
| Portfolio | Tenants, sites, devices, VPP membership and authorization checks |
| Telemetry | MQTT ingress, validation, TimescaleDB history and durable twins |
| Intelligence | Forecast baselines, flexibility and deterministic optimization |
| Dispatch | Dispatch state, allocations, commands, retries and recovery |
| Settlement | Immutable delivery settlement, rewards, ledger and CSV export |
| Simulator | Deterministic meter, solar, battery and EV behavior |
| Area | Stack |
|---|---|
| Backend | Java 21, Spring Boot 4.1, Spring Cloud Gateway, Spring Security |
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |
| Data | PostgreSQL, TimescaleDB, Flyway |
| Messaging | Apache Kafka, Eclipse Mosquitto MQTT |
| Identity | Keycloak |
| Observability | Micrometer, Prometheus, Grafana, ECS structured logging |
| Testing | JUnit 5, Testcontainers, Maven Failsafe, k6 |
| Delivery | Docker Compose, GitHub Actions |
The platform uses authenticated HTTP for immediate queries, Kafka for durable domain events and MQTT for device communication. Each backend service owns its database and migrations. Transactional outboxes, consumer inboxes, idempotency keys, immutable settlement inputs and scoped authorization protect the main distributed workflows.
Run all default backend tests from the repository root:
.\mvnw.cmd --batch-mode verifyRun frontend dependency, security, lint and production-build checks:
Push-Location apps/web
npm ci
npm audit --omit=dev
npm run lint
npm run build
Pop-LocationCross-service E2E and performance profiles are intentionally opt-in because they start real infrastructure:
.\mvnw.cmd "-Pe2e" verify
.\mvnw.cmd "-Pe2e,performance" verifySee Testing Guide for targeted test commands, expected results, manual checks and troubleshooting.
Start Prometheus and Grafana alongside the application:
docker compose --env-file infrastructure/compose/.env `
-f infrastructure/compose/compose.yml `
--profile app --profile observability up -d --waitOpen Grafana and select VoltWeave V1 Acceptance. Backend logs use ECS JSON and
propagate X-Correlation-Id, allowing one request to be followed through Gateway
and the owning service.
apps/web/ Next.js application
libs/event-contracts/ Versioned Kafka event contracts
services/api-gateway/ Public HTTP entry point
services/portfolio-service/ Tenant and resource ownership
services/telemetry-service/ Telemetry pipeline and device twins
services/intelligence-service/ Forecast, flexibility and optimization
services/dispatch-service/ Dispatch and command orchestration
services/settlement-service/ Settlement and rewards
simulator/simulation-service/ Deterministic device simulator
tests/e2e/ Cross-service acceptance tests
infrastructure/compose/ Local platform and operational scripts
docs/ Specifications, runbook and walkthroughs
Stop containers while preserving local data:
docker compose --env-file infrastructure/compose/.env `
-f infrastructure/compose/compose.yml --profile app downUse release.ps1 -NoBuild to restart existing images. Do not use --volumes
unless the stored sandbox data has been backed up and is intentionally being
deleted.
The V1 operations runbook covers logs, health, Kafka, JWT, database connections, device credentials, backup and deliberate reset procedures.
V1 is complete and reproducible through Docker Compose. It provides a software sandbox for the full observe-to-settle workflow.
The following remain outside the V1 boundary:
- certified physical device integrations;
- live electricity-market participation;
- real payment processing;
- Kubernetes and multi-region deployment;
- production TLS, managed secrets and infrastructure-specific capacity planning.