Spensara Spensara Knowledge Base & Documentation Repository
System Overview Brink & Borg Master Index (722 Docs) Spensara Platform Project Tracker

Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)
Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Categories

Branches (328)

Branch-specific documentation across extract-raw-xml, feature-fleet-import, kds_cdc_improvments, life-cycle, and tenat-admin.
branches/kds_cdc_improvments/monitor-specs/backend/Kds.Ai.Data/MonitorSpecs/daily-forecast.md 3,515 bytes · Updated Oct 23, 2026 10:44 AM EDT
Raw File

id: 3c2a6c51-9d8f-4f72-b7d1-6e5b2c0a9f41 name: Generate short-term hourly sales forecast kind: Forecast cron: 0 * * * * analysis_window: 90d comparison_periods: [7d, 28d]

Generate accurate short-term sales forecasts to support operational planning and staffing decisions. Forecast should estimate expected revenue for each of next 24 hours using historical order data and relevant external signals.

Output must contain hourly forecast values only, without explanations or descriptions of methodology.

Known Tables & Columns

curated.pos_orders

  • created_at (timestamp) - local order timestamp for hourly bucketing
  • created_at_utc (timestamp) - UTC order timestamp when local timestamp needs normalization
  • business_date (date) - business trading date
  • total (decimal) - order revenue
  • destination (varchar) - destination or fulfillment context
  • service_channel (varchar) - dine-in, pickup, delivery, or similar channel label when populated
  • fulfillment_channel (varchar) - downstream fulfillment grouping when populated

curated.pos_order_items (optional enrichment)

  • order_id (varchar) - join key to curated.pos_orders.order_id
  • item_id (integer) - menu item identifier
  • quantity (integer) - sold quantity
  • unit_price (decimal) - observed sold unit price
  • category_name (varchar) - sold item category when populated

Analysis Approach

  1. Extract completed historical orders from last 90 days using curated.pos_orders.
  1. Build hourly revenue history from curated.pos_orders.total.
  2. bucket by hour using created_at when present
  3. use created_at_utc only when local timestamp needs normalization
  4. keep business_date for day-level alignment and holiday comparisons.
  1. Aggregate historical sales into hourly revenue patterns, grouping by:
  2. hour of day
  3. day of week
  4. weekend vs weekday
  5. service or fulfillment channel when that split materially improves forecast accuracy.
  1. Identify recurring demand patterns such as:
  2. lunch vs dinner peaks
  3. late-night demand patterns
  4. channel-specific peaks.
  1. Detect recent anomalies in last 90 days such as:
  2. sudden sales spikes
  3. unusually low demand
  4. temporary effects caused by promotions or special events.
  1. Use curated.pos_order_items only when item or category mix materially explains demand shifts that are not visible from order totals alone.
  1. Enrich analysis using external signals, including:
  2. holidays and public events
  3. local events (sports games, festivals)
  4. weather conditions.
  1. Retrieve current weather conditions and forecast using get_weather_forecast to detect potential demand shifts.
  1. Build baseline hourly forecast for next 24 hours using historical hourly patterns.
  1. Adjust baseline forecast based on:
  2. upcoming weather conditions
  3. known events or holidays
  4. recent anomalies or short-term trends.
  1. Produce final hourly revenue forecast for next 24 hours.
  1. Output constraints:
  2. return forecast values only
  3. do not include explanations, reasoning, or methodology
  4. output must contain exactly 24 hourly forecast entries.
  1. Minimize database usage:
  2. prefer aggregated queries
  3. avoid requesting more than 3 queries unless necessary.

Output Format

Return structured list containing 24 hourly forecast values for next 24 hours. No explanations or narrative text should be included in output.