Technical report
Detailed notes, interpretation, and operational boundaries
This section documents what the published evidence means, how it was produced, and where the interface deliberately avoids making a stronger claim than the data supports.
Data preparation layer
A Python pipeline retrieves, validates, normalizes, aggregates, evaluates, forecasts, and exports versioned artifacts.
- Columnar Parquet files retain full prepared history and evaluation outputs efficiently.
- The model bundle, report JSON, human-readable reports, data-quality ledger, and public manifest are generated from the same run.
- Pipeline stages fail when required training or forecast rows are absent instead of publishing an empty success state.
Published data contract
The web layer consumes one compact manifest plus state-and-commodity JSON partitions rather than downloading the entire history on every route.
- Each partition declares market, observation, forecast, and seasonal records with its date range, byte size, and checksum.
- Stable slugs and market identifiers make routes shareable while visible labels preserve the official market names.
- Observed records and forecasts remain separate types so an estimate cannot silently replace a source observation.
Application layer
Next.js renders crawlable route content while focused client components handle filters, comparison state, copying, and downloads.
- Market and technical pages read prepared artifacts on the server; browser-side filtering operates on the published catalogue.
- URL parameters preserve market filters, selected comparisons, dates, quantities, and cost methods for reproducible shared views.
- Charts include text descriptions and expandable tables so visual summaries are not the only way to inspect values.
Operational and trust boundaries
The static release design favors reviewable artifacts, deterministic builds, and low runtime complexity.
- A new data refresh changes the generated manifest and partitions; the UI does not mutate source history at runtime.
- Language routes reuse the same numerical contract so translation cannot change prices, dates, or evidence counts.
- Deployment readiness depends on passing pipeline tests, application tests, type checks, lint, and a production build against the published artifacts.