DS - Battery Simulation Tool

Version: 0.3.0
Date: 2026-03-08
Status: Active prototype

1. Purpose

This Design Specification translates the Battery Simulation Tool requirements into a practical static-site implementation approach.

2. Architecture

• Static HTML/CSS/JS page under site/battery-simulation-tool/
• No backend requirement for the MVP
• CSV parsing in-browser
• Simulation engine in-browser
• Locally vendored Plotly bundle under site/battery-simulation-tool/js/vendor/
• Local browser storage only for optional presets in later phases

3. Module Design

Recommended modules:

• main.js
  • startup
  • module wiring
  • debounced automatic rerun on valid setting and mapping changes
• csv-parser.js
  • file reading
  • delimiter detection
  • header normalization
  • row parsing and number conversion
• simulation-engine.js
  • interval loop
  • charge/discharge decision logic
  • baseline and simulated outputs
  • annualized savings and payback estimate
• chart-adapter.js
  • transforms results into Plotly traces and layouts
  • keeps time-based chart ranges synchronized
  • derives capacity sweep chart data
• export-utils.js
  • CSV/JSON output generation
• ui.js
  • DOM wiring
  • validation feedback
  • KPI rendering
  • chart refresh
  • inline setting-help affordances

4. Data Design

The normalized interval record should contain:

• timestamp
• import energy
• export energy
• optional source metadata for combined tariff columns
• optional tariff information
• derived net value
• original row index for validation/debugging

For HomeWizard-oriented CSV files, cumulative import/export meter columns should be converted into per-interval values before simulation. If tariff-split columns such as Import T1 kWh and Import T2 kWh are present, the parser should combine them into one total import series. The same applies to export.

The simulation output record should contain:

• timestamp
• baseline import/export
• simulated import/export
• charge energy
• discharge energy
• state of charge

Summary outputs should remain in a separate object:

• total import/export before and after battery
• total charge/discharge
• self-consumption improvement
• price inputs used
• indicative savings

5. Visualization Design

Plotly is preferred because:

• zoom and pan are built in
• hover inspection is strong for analysis
• multiple traces can be compared clearly
• time-range inspection feels more like an analysis tool than a basic chart widget

6. UX Design Direction

• top explanation in plain language
• upload first, settings second, results third
• KPI cards before charts
• concise inline tooltips for battery settings
• assumptions and limitation note always visible
• validation feedback close to the upload/mapping step
• desktop-first layout with a single-column fallback on smaller screens

7. Technical Constraints

• the page must stay static-hosting compatible
• no client-side secrets
• no mandatory third-party backend
• large datasets should be handled without freezing the page under normal desktop conditions

8. MVP Design Choices

• one scenario only
• one reliable CSV path first
• tariff-split HomeWizard meters combined automatically
• manual pricing only
• daily aggregation for the comparison view
• deterministic simulation order
• no worker/thread complexity in the first build unless performance forces it

9. Implementation Position

The first release should optimize for reliability and clarity, not for maximum strategy complexity.