Calculation Methodology
Overview
WaterBalanceTools calculators use a layered data architecture. All factual values flow from canonical datasets, through entities, into calculators. No calculator embeds hardcoded scientific values. This design ensures that corrections to a single dataset record propagate automatically to every calculator, formula, and page that depends on it.
Data Flow Architecture
The data flow follows a strict hierarchy: (1) Canonical Datasets (data/datasets/) define factual values; (2) The Entity Layer (data/entities/, data/graph/) organizes these values by chemical, parameter, and pool type; (3) Generators read entities and datasets to produce HTML; (4) Calculators embed the resolved values from the canonical data layer at build time.
How Datasets Flow Into Entities
Each entity in the knowledge graph (e.g., "Free Chlorine") references a canonical dataset record for its ideal range and units via the rangeDataset and rangeRecord fields. The entity generator (generate-entities.js) resolves these references at build time using dataset-loader.js, replacing hardcoded strings with dataset values. The result is written to data/entities/chemicals.json and propagated to all entity pages.
How Entities Flow Into Calculators
Calculator generators read the entity index (data/graph/entity-index.json) to populate related topics, cross-references, and the trust panel. Calculator logic constants (ideal ranges, dosage coefficients, conversion factors) are loaded from data/datasets/ via the DatasetLoader utility module (js/data/dataset-loader.js).
How Calculations Are Generated
Pool chemistry calculations follow documented mathematical formulas drawn from industry-standard references. Each formula is versioned in data/trust/formulas.json. Calculator generators apply these formulas to user inputs and produce results. The formula version and dataset versions used are embedded in the trust panel of each calculator page.
Build Pipeline Order
The build pipeline runs in a fixed order: (1) generate-datasets.js compiles canonical datasets; (2) generate-entities.js resolves entity values from datasets; (3) Content generators (academy, formulas, glossary, reference) consume entities; (4) generate-trust.js compiles trust metadata and generates methodology/editorial/provenance pages; (5) inject-trust-panels.js embeds trust panels in calculators and version badges site-wide; (6) validate-trust.js validates trust completeness; (7) validate-datasets.js and validate-entities.js validate data integrity.
Maintenance
The calculation methodology is maintained by updating the relevant dataset source modules in scripts/data/. All methodology documentation is regenerated from data on each build. No manual editing of generated HTML is required or permitted.