Skip to content

ADR 0001: Financial Models Rework — Methodology Alignment, Terminology, Parameter Taxonomy, and Doc-Site Reorganization

  • Status: Accepted
  • Date: 2026-09-17
  • Deciders: Huashan Wang
  • Related: docs/context/contracts.md (Modeling Contract), docs/models/overview.md (Guiding Modeling Principles)

Context

The repository currently mixes homegrown model names (FFD, EED, VOR, BCS, SNS, EPS, FCS, VRS) with an evolving BUFM + Demand-Supply methodology. A substantial third-party artifact now exists — the 全球电池运营财务模型v12.xlsx workbook ("Maxwell's v12"), a formula-driven 3-line battery-operations model (Kenya Nairobi / Togo Lome / China Shenzhen) with batch-level SOH logic. The repo's declared contract is Python-first modeling with Excel as output artifact only; Maxwell's v12 violates this and uses partially inconsistent IRR conventions and a stale, statically pasted sensitivity block.

The owner has additionally directed a move away from MS Excel as a content representation toward open, portable formats (Markdown, CSV/JSON, Python), keeping spreadsheet-equivalents (e.g. Tencent smart sheets) only where the spreadsheet form is genuinely optimal.

A general rework is therefore required to align the repo with mainstream 2/3-wheeler e-mobility financial modeling methodology, reorganize the doc-site for readability, formalize the parameter taxonomy, and enable standalone per-market model deliverables. Kenya is the first priority market (launch imminent).

Decision

  1. Sequencing — docs first, engine second. Terminology, methodology pages, parameter taxonomy, and BUFM definitions are locked before Python engine rework begins.
  2. Terminology. docs/reference/terminology.md becomes the single controlled vocabulary, aligned to accepted industry usage (researched in Phase 1: TCO, EFC, SOH, utilization, swap pricing conventions, levelized cost metrics, payback, IRR/NPV, overprovisioning ratio). Repo-internal acronyms (FFD, EED, VOR, BCS, SNS, EPS, FCS, VRS) remain as model codenames but must be defined in industry terms.
  3. Doc-site information architecture (Phase 2 onward):
  4. Modeling basics, purposes, and how to read the doc-site
  5. Methodology and terminology
  6. BUFM definitions: business units and their interactions
  7. Output matrix: by business unit and by market
  8. Parameter taxonomy. Inputs are segmented into logical groups:
  9. Environment parameters — FX rates, interest rates, fuel and electricity costs, macro data
  10. Policy/fiscal parameters — import tariffs, income tax, subsidies (split from environment; present in Maxwell's v12 and decision-relevant)
  11. Operating parameters — CAPEX, labor, scale factors, modular unit sizes
  12. Assumptions — utilization rates, equipment failure rates, material losses
  13. Intermediary variables — computed, never inputs; serve as checking and cross-model comparison basis Conventions are defined as YAML/CSV data files plus Python dataclasses in Phase 3.
  14. Third-party artifacts. Maxwell's v12 is treated as a reference artifact for comparison only. It is extracted (static, read-only) for parameter and result comparison, not ported into the BUFM framework. The long-term intent is to bring its author to the BUFM/Python-first methodology, not to adapt this repo to the workbook.
  15. Output matrix and engine. One Python engine consuming per-market parameter sets; outputs organized as a business-unit × market matrix; sensitivity analysis runs as a reproducible script (correcting v12's static pasted values); a single IRR cash-flow convention is adopted repo-wide (resolving v12's Dashboard-vs-console mismatch).
  16. Standalone market models. Per-market bundles (first: Kenya) are generated on demand as HTML one-pager + CSV parameter pack. No .xlsx deliverables per the file-format policy; spreadsheet-equivalents only if a live what-if surface is explicitly requested.

Consequences

  • Positive: comparability with published industry models; auditable parameter lineage; per-market shareability without exposing the whole doc-site; reproducible sensitivity analysis.
  • Neutral: existing model codenames stay until Phase 2 renames them with link hygiene.
  • Negative/risk: one-time churn across docs and mkdocs nav; strict-build breakage must be fixed as encountered (KRR after every docs change). Engine rework (Phase 5) is deferred and must not start before the parameter schema is locked.