Architecture Overview

Connecting to the Database

Option 1: Neon Console (Recommended)

1. 1. Go to console.neon.tech
2. 2. Select your project and use the SQL Editor

Option 2: psql CLI

psql "postgresql://neondb_owner:****@ep-late-sky-ae17of8y.c-2.us-east-2.aws.neon.tech/neondb?sslmode=require"

Replace **** with the actual password from your DATABASE_URL environment variable.

Current Setup

1. Core Concepts

Draft vs Published Forecasts

Scheduling Binding Rules

2. Daily Cadence

⚠️ Republish Recommended for Acme Support

Draft forecast shows +6.2% daily volume vs published v20260114.1

Changes detected:
• Mon-Wed peak intervals shifted from 10:00-11:00 to 11:00-12:00
• Thursday volume increased 12% (marketing campaign effect?)

Actions: [Review Draft] [Publish Now] [Dismiss]

3. Locked Forecast Stability

Plan-of-Record (POR)

Now View (Real-Time Operations)

4. User Adjustments

Event Windows

Time periods where normal patterns don't apply — events override ML baseline.

{
  event_name: "Black Friday Sale",
  event_type: "promotional",           // promotional, operational, external
  start_date: "2026-11-27",
  end_date: "2026-11-30",
  impact_multiplier: 1.35,             // +35% expected volume
  intervals_affected: "all",           // or specific intervals
  notes: "Annual sale, expect 30-40% volume increase"
}

HOOP Changes (Hours of Operation)

Scenario Sliders with Guardrails

5. Trend Damping

Raw ML models can overreact to recent changes. Trend damping smooths predictions to reduce volatility while preserving genuine shifts.

trend_influence = 0.85 × exp(-0.12 × months_ahead)
mean_reversion = 1 - trend_influence

6. Accuracy Tracking (WAPE)

Health Labels

Baseline vs Published Comparison

7. Holiday Type Classification (PlanXpress™)

The holiday library uses a Type A/B/C classification system to categorize 27 US holidays by demand impact.

Holiday Types

D-3…D+7 Impact Envelope

Every holiday uses an 11-day impact envelope: 3 days before (D-3 to D-1), holiday day (D), and 7 days after (D+1 to D+7).

US Holiday Library (27 Pre-Configured)

Confidence-Based Blending

8. Forecasting Sub-Navigation UI

The forecasting module uses a consistent 4-tab sub-navigation across all pages.

9. Bias Detection & Calibration

Bias Classification

Calibration Layers

Final Forecast = ML Baseline
                 × Trend Adjustment
                 × Bias Calibration
                 × User Scenario Adjustments
                 × Event Window Multipliers

10. Intraday Recommendations

Trigger Thresholds

Allowed Moves

11. Deterministic Granularity Rules

Forecast granularity is determined by data quality, not user preference.

IF data_completeness < 0.7:
  → Use 60-minute (insufficient data for finer grain)

ELSE IF avg_volume_per_30min < 10:
  → Use 60-minute (small sample noise dominates)

ELSE IF variance_stability = "unstable" AND history_depth < 60:
  → Use 60-minute (need more history to trust 30-min patterns)

ELSE:
  → Use 30-minute

12. Output Formats

Core Prediction (per interval)

{
  date: "2026-01-16",
  interval_start: "09:00",
  interval_end: "09:30",               // or 10:00 for 60-min
  interval_index: 18,                  // 0-47 for 30-min, 0-23 for 60-min

  predicted_volume: 145,
  predicted_aht: 320,                  // Average handle time (seconds)
  predicted_occupancy: 0.82,           // Target occupancy

  confidence: {
    p50: { lower: 132, upper: 158 },
    p80: { lower: 118, upper: 172 },
    p95: { lower: 98, upper: 192 }
  }
}

Now View Output (intraday)

{
  timestamp: "2026-01-16T09:15:00Z",
  interval: "09:00-09:30",

  planned: {
    volume: 145,
    source: "v20260115.1"              // Published version
  },

  actual: {
    volume: 163,
    calls_in_queue: 8,
    current_asa: 24
  },

  projection: {
    rest_of_interval: 42,              // Expected additional calls
    rest_of_day_volume: 1240,
    rest_of_day_vs_plan: "+8.2%"
  },

  recommendation: {
    action: "extend_shifts",
    urgency: "moderate",
    details: "Consider extending 3 agents by 1 hour"
  }
}

1. Wave-Based Scheduling

Agents grouped into waves (A, B, C, D) - cohorts that start within a defined time window for easier supervision.

{
  waves: [
    { label: "Wave A", startTime: "08:00", agentCount: 12 },
    { label: "Wave B", startTime: "11:30", agentCount: 8 }
  ]
}

2. Team Cohesion Rules

Wide spread in start times creates supervision challenges. The engine enforces cohesion limits.

3. No-Start Windows

By default, no shifts can start during overnight hours to protect worker wellbeing.

4. Relief & Break Scheduling

Intelligent break and meal placement using 15-minute interval granularity.

Universal Rules

Slot Scoring Weights

5. Automatic Constraint Relaxation

When optimal placement isn't possible, constraints are intelligently relaxed in order.

Relief Scheduling Relaxation Levels

Shift Start Time Relaxation Levels

Immutable Constraints (NEVER Relaxed)

validateImmutableConstraints(schedule)
// Returns: { valid: boolean, errors: string[] }

// If validation fails:
// - schedule.isValid forced to false
// - Violations added to schedule.violations[]
// - Logged with severity: 'critical'

6. Erlang A/C Models

Industry-standard formulas for calculating agent requirements.

trafficIntensity = (callsPerInterval * ahtSeconds) / intervalSeconds
// Example: (50 calls * 300 sec AHT) / 1800 sec = 8.33 Erlangs

Schedule Generation API

{
  "business_unit_id": 42,
  "date": "2026-01-20",
  "erlang_model": "erlangA",
  "service_level_target": 0.80,
  "target_answer_time": 20,
  "shrinkage": 0.30,
  "shift_type": "5x8"
}

Key Features

Earnings Codes

Export Workflow