Chapter 1

Getting Started

Start here to understand the repo model, the workflow, and the first command path for a migrated market.

Subsections of Getting Started

Quickstart

This is the shortest supported path for using the repo.

Preconditions

  • Run commands from the repository root.
  • Have R available locally.
  • Install the minimal repo dependency used by validation:
install.packages("yaml")

Create A New Market/KPI

Rscript scripts/scaffold_market.R IT store_visits

This creates:

markets/IT/store_visits/

Fill In The Market Folder

At minimum:

  1. update config.yml
  2. implement transform.R
  3. implement decomp.R
  4. implement build.R
  5. update the market README.md
  6. record exact validated runtime versions in versions.lock

Validate

Validate one market:

Rscript scripts/validate_market.R markets/IT/store_visits

Validate all migrated markets:

Rscript scripts/validate_all.R

Build

Rscript scripts/build_market.R markets/IT/store_visits

Submit

  1. commit the market changes
  2. open a pull request
  3. product/engineering reviews for mergeability and standards

What This Does Not Yet Guarantee

The current scaffold enforces structure, config shape, and forbidden local-path patterns. Full runtime transform/predict/decomp/build verification is still a next-step enhancement once real market logic is migrated.

Getting Started

This repo is for market-specific implementations that sit on top of the shared product/package layer in forecast-mmmapi-r.

Run all commands from the repository root.

Typical Workflow

  1. Create or update a market/KPI folder under markets/.
  2. Keep market-specific logic in bounded files such as transform.R and decomp.R.
  3. Run validation locally.
  4. Open a pull request for product/engineering review.
  5. Build the upload artefact from the repo version, not from a local copy.

Standard Commands

Validate all migrated markets:

Rscript scripts/validate_all.R

Validate one migrated market:

Rscript scripts/validate_market.R markets/CN/store_visits

Scaffold a new market/KPI:

Rscript scripts/scaffold_market.R IT store_visits

Build one market/KPI:

Rscript scripts/build_market.R markets/CN/store_visits

First Things To Read

Current State

The repository structure and validation scaffold are in place. The next major step is to migrate real market logic, starting with China store visits.

Repo Model

This repository is intentionally separate from forecast-mmmapi-r.

Split Of Responsibility

forecast-mmmapi-r

  • reusable package/product code
  • API contract
  • packaging logic
  • shared templates and helpers

forecast-mmmapi-markets

  • market/KPI implementations
  • market configuration
  • bounded transform/decomp logic
  • validation entrypoints
  • build manifests and governance

Why Split Repos

Without this split, the reusable product repo tends to become a hybrid of:

  • library code
  • one-off market scripts
  • operational artefacts

That makes ownership weak and encourages drift. The market repo is meant to hold the operational market layer in one governed place.

Source Of Truth

For any migrated market/KPI:

  • the folder in this repo is authoritative
  • local SharePoint/Windows-drive copies are not authoritative
  • upload artefacts should be built from the Git version

Intended Outcome

The goal is a workflow where market logic is:

  • version-controlled
  • reviewable
  • reproducible
  • validated in a clean environment
  • traceable to a commit