CHAPTER 01Overview & Scope

Req. prefix: OVv0.2 draft

1.1Premise

Demand planners rarely accept a statistical forecast as-is. They know things the model does not: a brand-level marketing campaign, a customer's inventory strategy on a category, a promotion on a single barcode with a single customer. These forecast modifications are naturally expressed at whatever level of aggregation the knowledge exists — but planning systems consume them at the base grain.

HiLo.FM does exactly one job, and does it fast: it takes modification entries at any level (the HI space) and disaggregates them to the lowest level of granularity (the LO space: Product ID × Location ID × Week), keeping the two worlds in sync at interactive speed.

Position in the landscape
HiLo.FM is an upstream contributor, not a forecasting system. The reconciliation of overlapping modifications, their reasonability assessment, and their aggregation into a final consensus forecast happen in downstream processes outside this application.

1.2Objectives

OV-01The system MUST accept forecast-modification entries at any supported aggregation level (product hierarchy level, location, optional customer, week/month/quarter) and disaggregate each entry to LO grain.

OV-02Disaggregation MUST occur synchronously on entry creation and on every edit: the LO representation is up to date the moment the edit is acknowledged.

OV-03A batch process MUST re-disaggregate all entries against the current inputs (forecast, split tables, phase profiles). It runs nightly and is manually triggerable from the UI, with measured and displayed runtime (Ch. 06).

OV-04Every forecast-modification capability — entry management, preview, reporting, batch, reset — MUST be available through the UI, the webservice API (Ch. 08) and the MCP interface (Ch. 09) alike. Sole exception: the read-only master-data views of Ch. 07 exist in the UI only (D-23); the API/MCP expose master data solely as reference reads for scope construction.

OV-05The system MUST provide a one-action reset that restores a defined seed dataset, returning the demonstrator to base conditions (Ch. 10).

OV-06The system MUST be engineered for the scale targets of Ch. 06 (order of 100k products, tens of locations, millions of LO rows) even though it is a demonstrator.

1.3Explicit non-goals

The following are deliberately out of scope. Their absence is a design decision, not an omission.

Out of scope	Rationale
Consensus forecast publishing / merging of entries	Overlapping entries coexist; reconciliation is a downstream process.
Baseline forecast editing	The forecast is a read-only input, used only as a splitting basis.
Master-data ingestion or editing	Masters, forecast, split tables and phase profiles are synthetically generated per seed profile (Ch. 10); viewable read-only in the UI (D-23). No upload, no file formats, no editors.
Audit trail	Demonstrator simplification. No change history is kept beyond current state.
Authorization	Both accounts can do everything; roles are labels only (Ch. 10).
Full authentication	Reduced to two fixed username/password pairs.
Multi-tenancy, localisation, accessibility certification	Demonstrator simplification.

OV-07The system MUST NOT merge, net, prioritise or otherwise reconcile overlapping entries. Each entry's LO rows exist independently (Ch. 04).

1.4Quality attributes

Performance — the defining attribute. Interactive disaggregation and a demonstrably fast batch. Quantified targets in Ch. 06.
Determinism — the same inputs MUST always yield the identical LO output, including rounding (Ch. 06).
Exactness — each entry's LO rows sum exactly to its HI value, in statistical units, no drift.
Transparency — when disaggregation cannot proceed, the entry says so, with a reason, instead of guessing (Ch. 04).
UX quality — sub-second feedback for all interactive actions; details in Ch. 07.

1.5Document map

Ch. 02 defines terms and the shared example dataset. Ch. 03 specifies all data structures. Ch. 04 specifies the HI entry object and its state machine. Ch. 05–06 are the core: the splitting rules and the pipeline that applies them. Ch. 07–09 specify the three interfaces (human, webservice, agent). Ch. 10 defines seed data, reset and demo scenarios.