Variables and ledger engine

How SCALE's variable system works and how the AI turns inputs into a weekly ledger entry.

What this is

SCALE is a product-based business simulator that teaches supply chain fundamentals. It converts student decisions and contextual information into measurable outcomes: sales, costs, inventory levels, service quality, and profit. These outcomes are recorded as weekly ledger entries for each student's store.

The full loop (teacher → ledger)

The simulation follows a structured workflow:

Teacher creates a Class — Sets up the classroom with default templates and variable definitions
Student creates a Store — Chooses a store type (food truck, fine dining, campus kiosk, etc.)
Teacher creates a Scenario — Defines the week's story, conditions, and expectations
Student submits decisions — Makes choices using submission variables (the controls available to students)
Teacher creates a Scenario Outcome — Enters what actually happened in the world for that week
AI calculates results — Generates a ledger entry validated against the schema, including educational metrics

What "variable definitions" mean

A variable definition is a template that controls how a variable appears in forms and where it's used in the system. Each definition includes:

Key: The internal identifier
Label: The display name shown to users
Description: What the variable represents
Applies to: Where it's used (store type, submission, scenario, or outcome)
Data type: The kind of value it holds
Input type: How users interact with it (slider, dropdown, text field, etc.)
Default value: The starting value
Min/max: Acceptable range
Required: Whether it must be filled

Student perspective: Think of it like a control dial in a game—it has a label explaining what it does, and limits on how far you can adjust it.

Store type variables (baseline reality)

Store type variables define the fundamental constraints and characteristics of a student's business. They establish:

Storage capacity: How much inventory can be held
Cost structure: Purchase prices and holding costs
Efficiency: How effectively inventory converts to finished products
Pricing baseline: The default selling price (which students can adjust)

These variables create hard constraints (like maximum capacity), determine the starting state for the first ledger entry, and influence the cost per finished good. They set the baseline pricing that students can modify through their pricing decisions.

Inventory accounting rules (hard constraints)

The system uses three inventory buckets to track materials:

Refrigerated: Cold ingredients (cheese, meat, produce)
Ambient: Shelf-stable ingredients (flour, sauce base, spices)
Operating supplies: Non-food items (boxes, napkins, gloves)

Each bucket follows strict accounting rules:

Capacity limit: Ending units must not exceed capacity units
Conservation: Ending units = Beginning units + Received units − Used units − Waste units
Holding cost: Calculated as ending units × holding cost per unit for that bucket
Validation: The system checks consistency between inventory state and material flow, plus ensures revenue matches sales × realized unit price

Store type variable glossary

The following sections detail every store type variable, explaining what it means, how students experience it, and how teachers can use it to understand ledger outcomes.

Refrigerated bucket variables

capacity-units-refrigerated

What it is: Maximum refrigerated units that can be stored
Student view: "How full your fridge can get"
Teacher view: Sets the hard limit on refrigerated inventory, which can constrain sales and production if capacity is reached
Example: A store with capacity of 50 units vs 100 units: The higher capacity store can stockpile more inventory during low-demand periods, supporting higher sales during peak demand (increasing revenue). However, holding more inventory increases holding costs (ending units × holding cost per unit), reducing net profit.

starting-units-refrigerated

What it is: Refrigerated units available at the start of the simulation
Student view: "How much cold stuff you start with"
Teacher view: Initializes the first week's inventoryState.refrigeratedUnits
Example: Starting with 30 units vs 10 units: Higher starting inventory means less cash spent on initial orders (lower costs in week 1), and more inventory available to support sales immediately (potentially higher revenue). However, if demand is low, the extra inventory increases holding costs.

goods-per-unit-refrigerated

What it is: Number of finished goods that can be made from one refrigerated unit (conversion rate)
Student view: "How many products one fridge bundle can make"
Teacher view: Determines refrigerated usedUnits and the per-finished-good cost component from cold ingredients
Example: With goods-per-unit of 2.5 vs 1.5: To sell 50 products, the 2.5 store uses 20 units (50 ÷ 2.5) while the 1.5 store uses 33.3 units (50 ÷ 1.5). The higher conversion rate means lower ingredient costs per product (50 products × $10/unit ÷ 2.5 = $200 vs $333), improving profit margins while maintaining the same revenue potential.

avg-unit-cost-refrigerated

What it is: Cost to purchase one refrigerated unit
Student view: "How expensive the cold ingredients are"
Teacher view: Increases ingredient costs and can limit ordering when cash is constrained
Example: Unit cost of $8 vs $12: If a student orders 20 units, the $8 store spends $160 while the $12 store spends $240 (50% higher costs). This directly reduces profit margin. Higher costs also mean less cash available for other purchases, potentially limiting sales if inventory runs out.

holding-cost-per-unit-refrigerated

What it is: Weekly cost to store one refrigerated unit
Student view: "What it costs to keep stuff in the fridge"
Teacher view: Adds to holding costs when ending inventory includes refrigerated units
Example: Holding cost of $0.50/unit vs $1.50/unit: If ending inventory is 15 units, the $0.50 store pays $7.50 in holding costs while the $1.50 store pays $22.50. Higher holding costs penalize over-ordering, reducing profit when inventory is held. This encourages students to order more precisely to match demand.

Ambient bucket variables

capacity-units-ambient

What it is: Maximum ambient units that can be stored
Student view: "How much fits in your pantry"
Teacher view: Sets the limit on inventoryState.ambientUnits and affects whether large orders are feasible
Example: A store with capacity of 80 units vs 120 units: The higher capacity store can take advantage of bulk ordering discounts or prepare for high-demand scenarios, supporting more sales (higher revenue). However, larger inventory increases holding costs (ending units × holding cost per unit), reducing net profit if demand doesn't materialize.

starting-units-ambient

What it is: Ambient units available at the start of the simulation
Student view: "How much pantry stuff you start with"
Teacher view: Initializes the first week's inventoryState.ambientUnits
Example: Starting with 40 units vs 15 units: Higher starting inventory reduces initial cash outlay for orders (lower costs in week 1), and provides more buffer to support sales without immediate reordering (potentially higher revenue). If demand is lower than expected, the extra inventory increases holding costs.

goods-per-unit-ambient

What it is: Number of finished goods that can be made from one ambient unit
Student view: "How many products one pantry bundle can make"
Teacher view: Determines ambient usedUnits and the per-finished-good cost component from shelf-stable ingredients
Example: With goods-per-unit of 5.0 vs 3.0: To sell 60 products, the 5.0 store uses 12 units (60 ÷ 5.0) while the 3.0 store uses 20 units (60 ÷ 3.0). The higher conversion rate means lower ingredient costs per product (60 products × $4/unit ÷ 5.0 = $48 vs $80), improving profit margins while maintaining the same revenue potential.

avg-unit-cost-ambient

What it is: Cost to purchase one ambient unit
Student view: "How expensive the pantry ingredients are"
Teacher view: Increases ingredient costs and impacts profit margins
Example: Unit cost of $3 vs $5: If a student orders 25 units, the $3 store spends $75 while the $5 store spends $125 (67% higher costs). This directly reduces profit margin. Higher costs also consume more cash, potentially limiting the ability to order other inventory needed for production.

holding-cost-per-unit-ambient

What it is: Weekly cost to store one ambient unit
Student view: "What it costs to keep pantry stuff around"
Teacher view: Adds to holding costs when ending inventory includes ambient units
Example: Holding cost of $0.30/unit vs $0.80/unit: If ending inventory is 20 units, the $0.30 store pays $6.00 in holding costs while the $0.80 store pays $16.00. Higher holding costs reduce profit when inventory is held, encouraging students to order more precisely and avoid overstocking.

Operating supplies bucket variables (not for resale)

capacity-units-operating-supply

What it is: Maximum operating supply units (boxes, napkins, gloves) that can be stored
Student view: "How many box bundles you can store"
Teacher view: If supplies run out, production can be limited even when ingredients are available
Example: A store with capacity of 40 units vs 70 units: The higher capacity store can stockpile supplies to avoid production bottlenecks during high-demand periods, supporting more sales (higher revenue). However, larger inventory increases holding costs. If supplies run out, production stops even with ingredients available, capping revenue.

starting-units-operating-supply

What it is: Operating supply units available at the start of the simulation
Student view: "How many box bundles you start with"
Teacher view: Initializes the first week's inventoryState.notForResaleUnits
Example: Starting with 30 units vs 10 units: Higher starting inventory means less cash spent on initial supply orders (lower costs in week 1), and provides buffer to support production without immediate reordering (potentially higher revenue). If production is low, the extra supplies increase holding costs.

goods-per-unit-operating-supply

What it is: Number of finished goods that can be supported by one supply unit
Student view: "How many products one supply bundle can cover"
Teacher view: Determines supply usedUnits and the per-finished-good cost component from operating supplies
Example: With goods-per-unit of 12.0 vs 8.0: To sell 96 products, the 12.0 store uses 8 units (96 ÷ 12.0) while the 8.0 store uses 12 units (96 ÷ 8.0). The higher conversion rate means lower supply costs per product (96 products × $2/unit ÷ 12.0 = $16 vs $24), improving profit margins while maintaining the same revenue potential.

avg-unit-cost-operating-supply

What it is: Cost to purchase one operating supply unit
Student view: "How expensive boxes and napkins are"
Teacher view: Increases costs and affects whether reorders are affordable given cash constraints
Example: Unit cost of $1.50 vs $2.50: If a student orders 15 units, the $1.50 store spends $22.50 while the $2.50 store spends $37.50 (67% higher costs). This directly reduces profit margin. Higher costs consume more cash, potentially preventing reorders when supplies run low, which could limit production and revenue.

holding-cost-per-unit-operating-supply

What it is: Weekly cost to store one operating supply unit
Student view: "What it costs to keep extra boxes around"
Teacher view: Adds to holding costs when ending inventory includes operating supplies
Example: Holding cost of $0.20/unit vs $0.50/unit: If ending inventory is 12 units, the $0.20 store pays $2.40 in holding costs while the $0.50 store pays $6.00. Higher holding costs reduce profit when supplies are held, encouraging students to order more precisely to match production needs.

Pricing anchor variable (baseline price)

avg-selling-price-per-unit

What it is: Baseline selling price for one finished good for that store type
Student view: "Your normal product price before any discounts or markups"
Teacher view: The realizedUnitPrice is derived from this value multiplied by the student's pricing-multiplier. Revenue is calculated as sales × realizedUnitPrice
Example: Baseline price of $10 vs $14: If a student sells 80 products with a pricing-multiplier of 1.0, the $10 store generates $800 in revenue while the $14 store generates $1,120 (40% higher revenue). Higher baseline prices directly increase revenue per sale, but may reduce demand if customers are price-sensitive. The same costs applied to higher revenue results in better profit margins.

Note: Some store type presets may use avg-selling-price-per-product or avg-selling-price-per-finished-good as aliases. The system normalizes to a single pricing key before building the AI prompt, since the ledger and education metrics use one unified realized unit price concept.

Submission variables (student decisions)

These are the choices students make each week in response to a scenario. Each variable represents a strategic decision that affects outcomes.

demand-outlook

What it is: Student's forecast of how busy the week will be
Student view: "Do you think lots of people will show up?"
Teacher view: Biases the demand forecast and influences how other variables are interpreted

inventory-risk-tolerance

What it is: Student's priority between avoiding stockouts versus avoiding excess inventory
Student view: "Are you more worried about running out, or having too much leftover?"
Teacher view: Influences the tradeoff between safety stock and waste

reorder-intensity-refrigerated

What it is: How aggressively the student restocks cold inventory
Student view: "How much cheese and cold stuff do you want to buy?"
Teacher view: Affects receivedUnits, cash usage, and the risk of waste or high holding costs

reorder-intensity-ambient

What it is: How aggressively the student restocks pantry inventory
Student view: "How much flour and pantry stuff do you want to buy?"
Teacher view: Affects receivedUnits, cash usage, and the risk of stockouts

reorder-intensity-ops

What it is: How aggressively the student restocks operating supplies
Student view: "Do you have enough boxes and supplies?"
Teacher view: Prevents production bottlenecks when ingredients are available but supplies are not

production-push

What it is: How hard the student tries to convert inventory into sales
Student view: "Are you trying to make as many products as possible?"
Teacher view: Can increase sales when inventory is available, or increase waste if demand is lower than production

waste-discipline

What it is: How strict the student is about minimizing spoilage and waste
Student view: "Are you careful not to throw food away?"
Teacher view: Tends to reduce wasteUnits, but may reduce operational flexibility

pricing-multiplier

What it is: Adjustment to price relative to the store type baseline
Student view: "Do you want to offer a discount or charge more?"
Teacher view: Changes realizedUnitPrice, directly affects revenue, and can influence demand elasticity

service-level-focus

What it is: Student's priority between cost efficiency and customer service
Student view: "Do you want to save money, or make sure every customer gets a product?"
Teacher view: Influences tradeoffs between cost control and fulfillment rates

Scenario and scenario outcome (teacher-authored context)

Scenario

The teacher-created setup that defines the week's story and conditions. This includes expectations about supplier issues, weather, competitor actions, special events, and other contextual factors. Students use this information to make their decisions.

Scenario outcome

After students submit their decisions, the teacher enters what actually happened in the world for that week. This outcome applies to all students in the class, though its impact varies based on each student's store configuration and decisions. Examples include:

Actual weather conditions (storm disrupted deliveries)
Demand multiplier (higher or lower than expected)
Supply disruptions
Whether random events are enabled

Student perspective: The scenario is the setup you read before making decisions; the outcome is what actually happened in the story after you submitted.

What a ledger entry contains (weekly receipt)

Each ledger entry is a complete record of one week's business performance. It includes:

sales

What it is: Number of products sold
Student view: "How many products you sold"
Teacher view: Primary output metric that drives revenue

revenue

What it is: Money earned from sales (must align with sales × realizedUnitPrice)
Student view: "How much money customers gave you"
Teacher view: Total income for the week

costs

What it is: Total expenses (ingredients, holding costs, waste, expediting, etc.)
Student view: "How much money you spent"
Teacher view: All costs that reduce profit

waste

What it is: Waste in cost terms, tracked by bucket in the education object
Student view: "How much stuff you threw away"
Teacher view: Quantifies inefficiency and spoilage

cashBefore / cashAfter

What it is: Cash balance at the start and end of the week
Student view: "Money before, money after"
Teacher view: Tracks cash flow and liquidity

inventoryState

What it is: Ending inventory units by bucket (refrigerated, ambient, not for resale)
Student view: "What's left in the fridge, pantry, and supply closet"
Teacher view: Ending inventory that carries forward to the next week

netProfit

What it is: Weekly profit or loss (must align with cash delta: cashAfter − cashBefore)
Student view: "Did you make money or lose money?"
Teacher view: Bottom-line performance metric

randomEvent

What it is: Optional structured event explaining unusual outcomes
Student view: "Something random happened"
Teacher view: Documents unexpected events that affected results

summary

What it is: Narrative explanation of the week's outcomes
Student view: "A short story of your week"
Teacher view: Human-readable summary of what happened and why

education

What it is: Instructor-friendly breakdown including forecast vs actual demand, service level, realized unit price, cost breakdown, and per-bucket material flow
Student view: "Teacher notes that explain why things happened"
Teacher view: Detailed metrics for understanding performance and teaching concepts

How the AI turns variables into the ledger (step by step)

The AI processes variables through a structured sequence:

A) Establish demand

The system combines the scenario context, student's demand outlook, and any random events to determine both the forecasted and actual demand. This populates education.demandForecast and education.demandActual.

B) Determine realized unit price

The baseline selling price from the store type is multiplied by the student's pricing multiplier to calculate the actual price charged. This becomes education.realizedUnitPrice.

C) Compute per-finished-good costs

For each inventory bucket, the system calculates cost per finished good by dividing the average unit cost by goods per unit. This determines the ingredient cost component from each bucket.

D) Determine feasible production and sales

Production and sales are constrained by:

Actual demand
Inventory availability across all three buckets
Inventory accounting rules (capacity limits, conservation equations)

E) Determine receipts (ordering)

The system calculates how much inventory is ordered based on:

Reorder intensity for each bucket
Student's inventory risk tolerance
Available cash constraints

This determines receivedUnits and ultimately endUnits for each bucket.

F) Determine waste and holding costs

Waste is calculated from spoilage, overflow, and overproduction. Holding costs are computed as ending units × holding cost per unit for each bucket.

G) Compute totals and validate

Final calculations:

Revenue = sales × realizedUnitPrice
cashAfter = cashBefore + revenue − costs
Validation ensures all accounting rules are satisfied
The complete ledger entry is persisted

Why the education object matters

The ledger is designed as a teaching tool, not just a bookkeeping system. The education object provides:

Forecast vs actual comparisons: Shows how well students predicted demand
Service level metrics: Measures fulfillment and customer satisfaction
Pricing analysis: Reveals the impact of pricing decisions
Cost breakdown: Details where money was spent
Bucket-by-bucket flow: Tracks material movement through each inventory category

These metrics help teachers explain outcomes and help students understand the "why" behind their results, making the simulation a true learning experience.

More docs

Docs home Marketing home