Voltimax Platform

Appearance

Documentation Roadmap ​

This document outlines the roadmap for the Voltimax Platform documentation.

Reference: docs/ (VitePress), docs/guide/, docs/developer/

Architecture:

  • VitePress static site generation with search
  • Auto-generated reference docs (OCPP 2.1, SunSpec, Metrics)
  • Markdown with Mermaid diagram support
  • Style guide and writing templates in place

Phase D1: Core Documentation ​

Reference: docs/guide/

TaskStatusPriorityDescription
Architecture deep-dive❌ Not StartedHighSystem diagrams, component interactions, data flows
Deployment guide⚠️ PartialHighAzure deployment, on-premise options, requirements

Success Criteria:

  • Architecture documentation with C4 model diagrams (System, Container, Component)
  • Data flow diagrams for telemetry, pricing, and command pipelines
  • Complete Azure Container Apps deployment walkthrough
  • On-premise deployment guide with Docker Compose
  • Infrastructure requirements documented (compute, storage, network)

Implementation Status:

Completed:

  • ✅ VitePress infrastructure - Well-organized structure with 139 markdown files:
    • /docs/guide/ - User/operator guides
    • /docs/developer/ - Developer documentation
    • /docs/integration/ - Integration guides
    • /docs/reference/ - Auto-generated protocol/schema references
  • ✅ Getting Started (getting-started.md) - Prerequisites, clone/build, .NET Aspire setup
  • ✅ Key Concepts (concepts.md) - Domain model (Location, Asset, Gateway, Metrics)
  • ✅ Security Documentation (3 files):
    • Zero Trust model, RBAC, authentication
    • keycloak-setup.md (200+ lines) - Detailed Keycloak installation
    • technical-reference.md - Migration service and technical details
  • ✅ KeyVault Configuration (keyvault-configuration.md) - Secret management
  • ✅ Reference Documentation (60+ auto-generated files):
    • Metrics reference (50+ files from schemas/metrics/metrics.json)
    • Assets reference (10 Modbus device specs from YAML)
    • OCPP 2.1 messages and enumerations
    • SunSpec models (11 categories)
  • ✅ Developer Infrastructure (7 files on documentation workflows)
  • ✅ Style Guide (style-guide.md) - 11,400 lines of code and docs standards
  • ✅ Data Model (developer/schema/data-model.md) - Metric keys, units, asset types, and profiles

In Progress:

  • ⚠️ Deployment Guide - Only KeyVault configuration complete:
    • Missing: Azure Container Apps deployment steps
    • Missing: Bicep template documentation (infra/ has no docs)
    • Missing: Docker Compose for local deployment
    • Missing: On-premise/self-hosted setup procedures
    • Missing: Scaling and high availability guidance

Not Started:

  • ❌ Architecture Deep-Dive - Critical gap:
    • architecture.md is a 5-line stub with only "Next Steps" links
    • No system architecture diagrams (C4 model)
    • No component interaction flows (Platform ↔ Gateway, Frontend ↔ API)
    • No data flow diagrams (telemetry ingestion, pricing pipeline, command execution)
    • No decision architecture (strategy system)
    • No deployment topology diagrams
  • ❌ System Requirements - No hardware/software requirements documented
  • ❌ Configuration Reference - Environment variables, appsettings not documented
  • ❌ Troubleshooting Guide - No common issues, error messages, or diagnostics
  • ❌ API Getting Started - Scalar UI exists but no walkthrough guide
  • ❌ Stub Files Need Content:
    • assets.md (11 lines) - Overview section missing
    • gateways.md (33 lines) - "Under construction" notice only

Implementation notes:

  • Architecture diagrams should use Mermaid (VitePress renders these natively)
  • API reference uses Scalar UI (operational) but needs getting started guide
  • Multiple files reference "coming soon" sections creating link decay
  • Reference docs are comprehensive (auto-generated from schemas)
  • Writing infrastructure is excellent but content gaps remain

Phase D2: Developer Documentation ​

Reference: docs/developer/

Architecture:

  • Schema-driven development documentation
  • Style guide and writing templates
  • Code examples in dedicated repo folder (planned)
  • Automated testing of code samples (planned)
TaskStatusPriorityDescription
Debugging procedures❌ Not StartedHighCommon issues, logging, tracing, diagnostics
Testing documentation❌ Not StartedMediumUnit, integration, E2E testing guides
Contributing guidelines❌ Not StartedMediumBranch strategy, PR process, code review
API development guide❌ Not StartedMediumAdding endpoints, CQRS/Mediator patterns
Plugin development❌ Not StartedLowGateway protocol plugin SDK documentation

Success Criteria:

  • Debugging guide covers local Aspire debugging and remote gateway debugging
  • Testing documentation includes unit tests, integration tests, and Playwright E2E
  • CONTRIBUTING.md exists with branch strategy and PR process
  • Architecture overview with component diagrams for each major subsystem

Implementation Status:

Completed:

  • ✅ Documentation Infrastructure (7 files, 85+ lines each):
    • documentation.md - Structure overview
    • documentation/structure.md - Section organization
    • documentation/writing.md - Writing guidelines (8,600+ lines)
    • documentation/templates.md - Template selection (8,450+ lines)
    • documentation/vitepress.md - VitePress configuration (6,840+ lines)
    • documentation/workflows.md - Documentation workflows (9,392+ lines)
    • documentation/generation.md - Auto-generation process (7,700+ lines)
  • ✅ Schema Documentation (4 files):
    • schema/index.md - Schema-driven development overview
    • schema/metrics.md - Metrics schema generation
    • schema/assets.md - Modbus device generation
    • schema/troubleshooting.md - Schema issues
  • ✅ Style Guide (style-guide.md) - 11,400 lines of standards

Not Started:

  • ❌ Debugging Procedures - Critical for developers:
    • No local debugging guide (.NET Aspire)
    • No remote gateway debugging procedures
    • No logging configuration examples
    • No Elastic APM tracing walkthrough
    • No troubleshooting decision tree
    • No common issues guide
    • No performance diagnostics
  • ❌ Testing Documentation:
    • No unit testing guide
    • No integration testing procedures
    • No E2E testing with Playwright guide
    • No test fixtures documentation
  • ❌ Contributing Guidelines:
    • No CONTRIBUTING.md
    • No branch strategy documented
    • No PR review process
    • No code review criteria
  • ❌ Architecture Overview:
    • Referenced as "coming soon" in developer/index.md
    • No component diagrams for Gateway, Platform API, Frontend, Data pipeline
  • ❌ API Development Guide:
    • No guidance for adding endpoints
    • No Mediator/CQRS pattern examples
    • No validation and error handling patterns
  • ❌ Plugin/SDK Documentation:
    • Custom protocol SDK not yet implemented (deferred per roadmap)
    • Plugin system architecture undocumented

Undocumented Implemented Features:

  • Gateway strategy framework (IStrategy, AbstractStrategy, StrategyFactory)
  • Modbus TCP/RTU protocol handlers with 7 supported devices
  • OCPP 2.1 support
  • Azure Functions pipeline (pricing, telemetry)
  • Metrics infrastructure (20+ query handlers)
  • Observability (OpenTelemetry, Elastic APM, Serilog)

Implementation notes:

  • Writing infrastructure is excellent (style guides, templates, workflows)
  • Reference documentation is comprehensive (auto-generated)
  • Developer barriers are high without debugging/testing/contributing guides
  • Code samples should be extracted and tested in CI (not implemented)
  • Contributing should follow conventional commits with commitlint (not documented)