Skip to content

Instantly share code, notes, and snippets.

@prfraser

prfraser/auto_sales_predictions.md

Created May 30, 2025 04:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save prfraser/e4c98935e15d8733f8fb576739bbe333 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save prfraser/e4c98935e15d8733f8fb576739bbe333 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
auto_sales_predictions.md

⏺ How Automatic Sales Predictions Work with the "Average of Dates" Strategy

Overview

When an organisation uses the "average of dates" forecasting strategy, the system automatically creates sales predictions to help with roster planning. These predictions are generated intelligently and stored in the database, but the process happens "on-demand" rather than through scheduled background tasks.

The Complete Chain of Events

1. Initial Setup

  • Organisation sets their forecasting strategy to "average of dates" in their settings
  • This tells the system to use historical sales averaging for predictions

2. Trigger Point: User Opens Roster Planning

  • When a manager or admin visits the roster overview page to plan shifts
  • When they select new date ranges or locations to view
  • When they navigate to any week/period that needs roster planning

3. Automatic Historical Analysis

The system immediately and automatically:

  • Examines the previous 5 weeks of historical sales data
  • Identifies which dates had good, reliable sales data
  • Determines the best historical dates to use for creating predictions

4. Intelligent Date Selection Algorithm

The system uses smart logic to choose which dates to average:

Scenario A - Current Date Has Historical Data:

  • If planning for a Tuesday, and there's good Tuesday sales data from previous weeks
  • Uses only Tuesday data from recent weeks for the most accurate prediction

Scenario B - Current Date Has No Historical Data:

  • If planning for a new day/time that hasn't been tracked before
  • Finds the most recent 3 days that had strong sales data
  • Uses those days as the basis for prediction

5. Automatic Prediction Creation

  • Calculates the average sales from the selected historical dates
  • Applies any configured growth percentage (if the business is growing/declining)
  • Generates predictions for each hour/time period throughout the day
  • Automatically saves these predictions as PredictedStoreStat records in the database

6. Immediate Availability

  • Predictions are instantly available in the roster interface
  • Managers can see predicted sales volumes while planning shifts
  • These predictions help determine how many staff to schedule

7. Ongoing Updates

  • Process repeats automatically whenever someone views roster planning for new dates
  • Predictions stay current as new historical data becomes available
  • No manual intervention required from administrators

Key Benefits of This Approach

Responsive & Current: Predictions are created when needed, using the most recent data available

Intelligent Selection: The system automatically chooses the most relevant historical dates rather than using arbitrary averages

No Maintenance Required: Unlike scheduled forecasting systems, this requires no ongoing maintenance or monitoring

User-Driven: Predictions are created as managers actually do their planning work, ensuring they're always relevant

Automatic Storage: Once created, predictions are saved for future reference and reporting

@prfraser
Copy link
Author

prfraser commented May 30, 2025

When Existing Predictions Are Present: Skip or Recreate?

The Answer: It Skips Creation (Does Nothing)

When someone visits the roster overview and PredictedStoreStat records already exist for those dates, the system does not recreate them. Here's the specific logic:

The Decision-Making Process

  1. Primary Check: Demand Configuration Exists
  • The system first checks if a "demand configuration" already exists for that date/location
  • If predictions have been created before, this configuration will be populated
  • If configuration exists → Auto-prediction is completely skipped
  1. Secondary Check: Individual Prediction Level
  • Even if the system gets to the point of generating predictions
  • It checks for existing individual prediction records
  • Filters out any predictions that already exist
  • Only creates predictions for time slots that have no existing data
  1. Protection Against Overwriting
  • The auto-prediction system has a built-in flag replaceExistingPredictions = false
  • This ensures existing predictions are preserved during automatic processes
  • Users' manual adjustments or previously calculated predictions are not lost

What This Means Practically

Scenario A: Manager Opens Last Week's Roster

  • Predictions already exist from when they planned it before
  • Result: Nothing happens - existing predictions are preserved
  • Page loads faster since no new calculations needed

Scenario B: Manager Opens Next Week's Roster

  • No predictions exist yet for future dates
  • Result: Auto-prediction runs - creates new predictions for unplanned dates

Scenario C: Manager Manually Adjusts Predictions

  • They override automatic predictions with their own numbers
  • Later, someone else visits the same roster page
  • Result: Manual adjustments are preserved - no overwriting occurs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment