Demand Forecasting

The Problem

Accurate demand forecasting drives production planning, inventory management, and distribution. It depends on historical demand data — knowing how much a product sold in previous months to predict the next.

But product codes change constantly: reformulations, repackaging, regulatory requirements, market restructuring. Each change breaks the demand history — the new code starts with zero history, even though it's the same product.

Walkthrough Example

A shampoo product goes through two code changes over three years. Here's how the chain system tracks it:

The resulting Product Family:

Splits & Merges

Families can also split (one code becomes two) or merge (two codes become one), forming a directed acyclic graph (DAG):

Key Concepts

Event Transition Types

Each event contains one or more transitions. There are three types:

Example Event Payload

{
  "iso_country_code": "PL",
  "transitions_write": [
    {
      "code_type_id": "IPC",
      "type": "INTRO",
      "date": "2023-06-01",
      "introduction_code": 1002
    },
    {
      "code_type_id": "IPC",
      "type": "chain",
      "date": "2023-06-01",
      "introduction_code": 1002,
      "discontinuation_code": 1001
    },
    {
      "code_type_id": "IPC",
      "type": "DISCONT",
      "date": "2023-06-01",
      "discontinuation_code": 1001
    }
  ]
}

Validation Rules

Your API must reject these invalid scenarios with HTTP 400:

How Testing Works

The provided test script validates your API in three phases:

API Endpoints

Setup

Events

Product Families

Resolution

Data Model

The system is built around events containing code transitions, which produce generations grouped into product families.

erDiagram
    COUNTRY {
        string code PK
        string name
    }

    EVENT {
        int id PK
        string iso_country_code FK
        string comment
    }

    CODE_TYPE {
        string id PK
        string type
    }

    CODE_TRANSITION {
        int id PK
        int event_id FK
        string code_type_id FK
        string type
        date date
    }

    INTRODUCTION {
        int id PK
        int code_transition_id FK
        bigint introduction_code
    }

    DISCONTINUATION {
        int id PK
        int code_transition_id FK
        bigint discontinuation_code
    }

    CHAIN {
        int id PK
        int code_transition_id FK
        bigint introduction_code
        bigint discontinuation_code
    }

    PRODUCT_FAMILY {
        int id PK
        string code_type_id FK
        string identifier
        string iso_country_code FK
    }

    GENERATION {
        int id PK
        int product_family_id FK
        int introduction_id FK
        int discontinuation_id FK
    }

    GENERATION_LINK {
        int id PK
        int predecessor_id FK
        int successor_id FK
        int source_transition_id FK
    }

    COUNTRY ||--o{ EVENT : "has"
    COUNTRY ||--o{ PRODUCT_FAMILY : "has"
    EVENT ||--o{ CODE_TRANSITION : "has"
    CODE_TYPE ||--o{ CODE_TRANSITION : "has"
    CODE_TRANSITION ||--o| INTRODUCTION : "is"
    CODE_TRANSITION ||--o| DISCONTINUATION : "is"
    CODE_TRANSITION ||--o| CHAIN : "is"
    CODE_TYPE ||--o{ PRODUCT_FAMILY : "has"
    PRODUCT_FAMILY ||--o{ GENERATION : "has"
    CODE_TRANSITION ||--o{ GENERATION : "introduction"
    CODE_TRANSITION ||--o{ GENERATION : "discontinuation"
    GENERATION ||--o{ GENERATION_LINK : "predecessor"
    GENERATION ||--o{ GENERATION_LINK : "successor"
    CODE_TRANSITION ||--o{ GENERATION_LINK : "source"
        

Reference Data

Family Computation Logic

After all events are ingested and the recompute endpoint is called, your system must:

1. Collect all code transitions, grouped by country and code type.
2. Sort transitions chronologically (by date), with tie-breaking: Introductions first, then Chains, then Discontinuations.
3. Build a directed graph where:
   • Each Introduction creates a new node (generation).
   • Each Chain creates an edge between two nodes (linking predecessor to successor).
   • Each Discontinuation sets the end date on an existing node.
4. Identify weakly connected components in the graph — each component is a product family.
5. Persist the families, generations, and links.

Reference Server (for inspiration only)

A working example of the Chains system is hosted at https://chains.durczok.ovh. It implements the same API surface you are being asked to build and ships with a browsable UI so you can explore the data model, poke at endpoints, and see what “correct” behaviour looks like before (or while) writing your own implementation.

If you would like to play with it, reach out to me directly and I will share a username and password. The server uses HTTP Basic authentication on every request — credentials will be provided out-of-band, so please never commit them to git.

Treat the reference server purely as a sandbox for learning and inspiration.

If you do want to explore it programmatically (e.g. from a notebook), the authentication pattern with requests looks like this:

import os, requests

BACKEND = requests.Session()
BACKEND.auth = (os.environ["CHAINS_USERNAME"], os.environ["CHAINS_PASSWORD"])

r = BACKEND.get("https://chains.durczok.ovh/api/events/")

See notebooks/server_example.py for a fuller example.

Getting Started

1. Set up a web server listening on http://localhost:5050.
2. Implement the event ingestion endpoint with full validation logic.
3. Implement the family recomputation engine.
4. Implement the resolution endpoints.
5. Run the test script against your server and iterate until all tests pass:

python test_api.py --base-url http://localhost:5050 --total 100

Good luck!