Chapter 2

Market Contract

Define the market folder structure, configuration contract, and the minimum documentation each market implementation must carry.

Subsections of Market Contract

Market Folder Contract

Each market/KPI implementation should live under:

markets/<MARKET>/<KPI>/

Required Files

  • config.yml
  • transform.R
  • decomp.R
  • build.R
  • validate.R
  • README.md
  • versions.lock

Optional support folders:

  • fixtures/
  • manifests/

Expected Functions

transform.R

transform <- function(data, config) { ... }

decomp.R

decomp <- function(data, model, config) { ... }

build.R

build_api <- function(config) { ... }

Hard Rules

  • No hard-coded local Windows, SharePoint, or OneDrive paths in committed code.
  • No setwd().
  • No hidden reads from analyst-local infrastructure inside transform() or decomp().
  • Package calls should be namespaced explicitly.
  • The same model representation must be used consistently across transform, predict, and decomp.

Config Expectations

At minimum, config.yml should describe:

  • market code
  • KPI name
  • owner
  • week start convention
  • model source
  • mapping source
  • input locations
  • decomp regex/configuration
  • validation requirements

See Config Reference for a worked example and field notes.

Market README Requirements

The market README.md is required and should include:

  • purpose
  • owner
  • expected input artefacts
  • market-specific assumptions
  • validation status
  • transition notes from local scripts

See Market README Template.

Why This Contract Exists

The contract exists to stop each market drifting into a private implementation that is hard to review, hard to reproduce, and inconsistent with the product workflow.

Config Reference

Each market/KPI folder must define a config.yml.

Example

market_code: CN
kpi: store_visits
owner: Winnie Chen
week_start: 7

artifact_name: CN-store_visits

model:
  source: external_rds
  path: data/local/model/_sv_info.rds
  object_path: model
  api_model_policy: use_one_consistent_model_for_predict_and_decomp
  update_strategy: explicit

mapping:
  source: model_rds
  object_path: tbl_map

inputs:
  raw_data: data/local/input/cn_raw_import.csv
  fixed_forecast: data/local/input/cn_fixed_forecast.csv

decomp:
  synergy_vars_regex: "^(m_|family_|fammed_|pro_|orgsoc_|pr_)"
  adstock_var_regex: "..."

validation:
  require_clean_session: true
  require_predict: true
  require_decomp: true
  forbid_local_paths: true
  forbid_hidden_imports: true

Required Top-Level Keys

  • market_code
  • kpi
  • owner
  • week_start
  • artifact_name
  • model
  • mapping
  • inputs
  • decomp
  • validation

Field Notes

market_code

  • short market identifier, for example CN, IT, UK

kpi

  • KPI folder name and logical build target

owner

  • named analyst or market owner

week_start

  • 1 for Monday
  • 7 for Sunday

artifact_name

  • human-readable artefact stem used by build logic

model.source

  • where the model object comes from
  • current scaffold assumes an external RDS-style source, but this can evolve

model.path

  • explicit path to the model artefact used by the market

model.object_path

  • object name or object-path identifier within the artefact

model.api_model_policy

  • expected consistency rule for predict/decomp

model.update_strategy

  • how model updates are handled, for example explicit replacement or inherited

mapping

  • where the mapping table comes from

inputs.raw_data

  • explicit market input artefact used by transform

inputs.fixed_forecast

  • fixed forecast input if applicable

decomp.*

  • market-specific decomp regex or configuration

validation.*

  • switches describing required validation behaviour

Current Limitation

The current repo validates config shape and week-start values. It does not yet validate a full schema of allowed values for every nested field.

Market README Template

Every market/KPI folder requires a README.md.

Minimum Required Content

Title

  • market name
  • KPI name

Purpose

  • what this market folder implements

Owner

  • named analyst owner
  • named product/engineering reviewer if useful

Input Artefacts

  • what model artefact is expected
  • what raw data is expected
  • whether fixed forecast input is required

Market-Specific Assumptions

  • week start convention
  • date/calendar assumptions
  • important transform/decomp quirks

Validation Status

  • scaffold only
  • partially migrated
  • fully migrated and validated

Notes

  • known risks
  • transition notes from local scripts

Why This Matters

The market README is meant to make the folder understandable without relying on oral context or analyst memory.