Technical Deep Dive

How the Optimizer works

A plain-English explanation of the AI scheduling system behind Shift Optimizer — written for hiring managers, not just engineers.

Instead of manually juggling spreadsheets, this app mathematically proves the best possible schedule — handling impossible constraints gracefully while maximizing employee happiness.

↗ Open Live App ↗ GitHub

The Technology

3 AI layers working together

One guarantees rules, one maximizes happiness, and the newest layer ensures the system never crashes even when the math is "impossible".

🧮

Layer 1

Constraint Programming — OR-Tools CP-SAT

Google's CP-SAT solver assigns shifts across 30 employees, 3 departments, and 7 days simultaneously. It doesn't try schedules one by one — it reasons over all possibilities at once using constraint propagation and branch-and-bound search. The result is a mathematically proven optimal schedule, not a heuristic guess.

Provably optimal — not trial and error
⚖

Layer 2

Soft Constraint Optimization — Penalty Minimization

Beyond just satisfying rules, the optimizer minimizes a penalty score representing employee dissatisfaction. "Must-off" days are hard constraints (never violated). "Prefer-off" days and shift preference mismatches carry numerical penalties. The solver finds the schedule that minimizes total employee unhappiness.

Hard rules guaranteed + soft preferences maximized
🛡

Layer 3 (New)

Heuristics & Slack Variables — Edge-Case Handling

Traditional solvers crash or return "No Solution" when constraints are too tight (like having too few staff). This engine intercepts impossible scenarios with a heuristic pre-check. If needed, a "Best Effort Mode" converts hard minimum-staffing rules into soft constraints using slack variables with massive penalties. It mathematically guarantees the best possible schedule even when short-staffed, flagging the gaps for the manager.

Heuristic Pre-check · Slack Variables · Feasibility

Constraint Design

Hard rules vs. soft preferences

The key engineering decision: which rules must never be broken, and which are best-effort goals the optimizer tries to satisfy?

Hard Constraint — Always enforced
Must-off days
Absolute unavailability (illness, appointments). The solver will never assign a shift on these days — no exceptions.
Hard Constraint — Always enforced
Department staffing minimums
Each shift must have at least the required number of staff. (Can be relaxed into a soft constraint via Best Effort Mode if mathematically impossible).
Hard Constraint — Always enforced
Manager & certified staff coverage
At least one manager/assistant manager per day, and (for Grocery) one certified staff per shift. Guaranteed by the model structure.
Hard Constraint — Always enforced
Max consecutive working days
No employee works more than the configured consecutive days. Prevents burnout and complies with labor regulations.
Soft Constraint — Best effort
Prefer-off days (penalty: 100)
The optimizer tries to respect these, but may assign shifts if no valid schedule exists otherwise. Each violation adds 100 to the penalty score.
Soft Constraint — Best effort
Shift time preference (penalty: 50)
Employees who prefer morning shifts get penalized 50 points for each afternoon or night shift assigned. The optimizer minimizes the total across all employees.

The Process

From preferences to optimal schedule

Here's exactly what happens when you click "Optimize Shifts."

1

Decision variables are created (one per slot)

For every combination of employee × day × shift, a binary variable is created: 1 = assigned, 0 = not assigned. With 30 employees × 7 days × 3 shifts, that's 630 variables the solver must assign simultaneously.

# 630 binary variables
x = {
  (e, d, s): model.NewBoolVar(f"x_{e}_{d}_{s}")
  for e in range(30)  # employees
  for d in range(7)   # days
  for s in range(3)   # shifts
}
2

Hard constraints are added (or relaxed via Slack Variables)

Each business rule becomes a mathematical constraint. However, if "Best Effort Mode" is enabled, minimum staffing requirements are relaxed using *slack variables* so the solver doesn't fail when understaffed.

# Best Effort Mode: Slack Variables
if allow_understaffing:
  shortage = model.NewIntVar(0, min_req, "short")
  model.Add(sum(x) + shortage >= min_req)
  penalties += shortage * 10000
else:
  # Strict hard constraint
  model.Add(sum(x) >= min_req)
3

Soft constraints become a penalty objective

Prefer-off days and shift preferences are converted into penalty terms. The solver's objective is to minimize the total penalty score — meaning it will try its hardest to honor soft preferences, but won't break hard rules to do so.

# Soft NG: penalty 100 per violation
penalties += x[e, d, s] * 100

# Wrong shift type: penalty 50
if s != preferred_shift:
  penalties += x[e, d, s] * 50

model.Minimize(sum(penalties))
4

CP-SAT solves and returns the optimal assignment

The solver explores the solution space using constraint propagation (eliminating impossible assignments early) and branch-and-bound search (proving no better solution exists). It returns the schedule with minimum penalty score within the time limit, along with a satisfaction score for each employee.

Business Applications

How this translates to your business

Mathematical optimization transforms shift scheduling from a painful weekly chore into a solved, scalable, and auditable process.

⏳

Hours of Manager Time Saved

Manually building schedules for 30+ staff typically takes hours each week. The optimizer produces a valid, optimized schedule in under 15 seconds. If understaffed, it flags exactly where the gaps are, allowing managers to make targeted human decisions rather than starting from scratch.

⚖

Zero Compliance Violations

Labor rules (max consecutive days, minimum certified coverage, mandatory manager presence) are guaranteed by the model — not enforced by human memory. Every schedule produced is provably compliant with every configured rule.

😀

Higher Employee Satisfaction

The optimizer explicitly quantifies and minimizes employee dissatisfaction. Rather than ignoring preferences when scheduling gets complex, it mathematically balances fairness across the entire team — reducing turnover-inducing schedule conflicts.

Why It Matters

What this demonstrates

🧮

Operations Research Applied

Shift scheduling is a classic OR problem. Formulating it correctly — choosing which constraints are hard vs. soft, using slack variables to prevent crashes, and weighting penalty terms — requires deep understanding of both the business problem and the solver's capabilities.

🌟

Production-Grade Solver

OR-Tools CP-SAT is the same solver used internally at Google. Using it in a portfolio project demonstrates familiarity with enterprise-grade optimization tools, not just academic toy problems.

📋

Full-Stack Data Product

The app goes from user input to deployed web product: Streamlit UI, Python optimization engine, Plotly visualizations, bilingual i18n, and Streamlit Cloud deployment. End-to-end data product thinking.

⚖

Explainable Results

The satisfaction score and per-employee breakdown make optimization results auditable and understandable — not a black box. Managers can see exactly why each schedule was chosen and where trade-offs were made.

Try It

See it in action

The app is live. Randomize preferences and constraints, then click Optimize.

↗ Open Live App ↗ GitHub ← Back to Portfolio