Technical Documentation for IT Evaluators

ESS+FSR Technical Architecture

Complete technical documentation for CAIRE's dual-model automatic staffing discovery system. Understand the architecture, algorithms, API integration, and performance characteristics.

Back to Customer Overview Try Interactive Demo
System Overview: Dual-Model Architecture

CAIRE uses a dual-model optimization architecture that combines two specialized engines:

ESS: Employee Shift Scheduling

Determines who works when and on which shifts, based on hourly demand curves and labor law constraints.

FSR: Field Service Routing

Assigns which employee visits which client and optimizes routes to minimize travel time.

graph LR V[45 Visits] --> ESS[ESS: Shift Planning] ESS --> S[9 Employees
14 Shifts] S --> FSR[FSR: Route Optimization] FSR --> R[Optimized Routes
All Visits Assigned] R --> C{Converged?} C -->|No| ESS C -->|Yes| Done[Present to Planner] style ESS fill:#9333EA,color:#fff style FSR fill:#14B8A6,color:#fff style Done fill:#22C55E,color:#fff

Why Two Models?

Traditional schedulers only optimize routes for pre-defined shifts. But how do you know how many employees you need? Using FSR alone leads to a catch-22: if you send a full set of shifts (e.g. one per employee per day), the solver assigns visits to some shifts and leaves others empty—so you get "shifts with no visits." If you send only the shifts you think you need (cold start), the solver often cannot assign all visits and you get "unassigned visits." FSR does not decide how many shifts to create; it routes visits to shifts you already defined. ESS+FSR avoids this: ESS is demand-driven and creates exactly the shifts needed; FSR then only routes to those shifts, so you get no empty shifts and full visit coverage. CAIRE uses the dual model to automatically discover optimal staffing levels:

Aspect Traditional Approach CAIRE ESS+FSR
Staffing Input Manual configuration required Automatic discovery from demand
Employee Count You guess (8? 10? 12?) System calculates (discovers: 9)
Shift Times You define manually System optimizes automatically
Travel Overhead Assumed or ignored Learned from actuals data

Key Innovation: ESS and FSR work iteratively. ESS estimates travel overhead and creates shifts. FSR reveals actual travel needed. If the delta is >5%, ESS adjusts and re-runs. Typically converges in 2-3 iterations.

ESS: Employee Shift Scheduling Engine

What is ESS?

Employee Shift Scheduling (ESS) is a mathematical optimization model that determines who works when and on which shifts, based on demand curves and labor law constraints. It treats demand as input and staffing as output.

Core Functionality

  • Input: Demand curve (employees needed per hour), employee pool, availability, labor law rules
  • Output: Shift assignments (employee ID, start time, end time), activated employee count, total cost
  • Optimization Goals: Minimize total staffing cost while covering 100% of demand

Timefold API Integration

CAIRE uses Timefold's commercial optimization solver via cloud API:

// Generate demand curve from visits const demandCurve = generateDemandCurve(visits, overheadMultiplier); // Call ESS API const essResult = await essClient.solve({ employees: mapEmployeesToESS(employees), globalRules: { minimumMaximumShiftsPerHourlyDemand: demandCurve, periodRules: swedishLaborLawRules, costGroups: costOptimizationConfig } }); // Result: Shift assignments console.log(essResult.shiftAssignments); // [{ employeeId: "emp_123", start: "08:00", end: "16:00" }, ...]

Swedish Labor Law Automation

ESS automatically enforces Swedish kollektivavtal rules:

  • Max 40h/week (preferred), max 48h/week (hard limit)
  • 11h daily rest (EU Working Time Directive)
  • Max 5 consecutive working days
  • Break requirements after 5h work
  • Weekend rest rules

Cost Optimization

ESS prioritizes fixed-contract employees (zero activation cost) over hourly staff (500 SEK activation cost):

Fixed Contract Employees

Activation cost: 0 SEK (already salaried)
Strategy: Fill available hours first

Hourly Staff

Activation cost: 500 SEK
Strategy: Activate only when demand exceeds fixed capacity

Demand Curve Generation

The Critical Bridge: ESS has no concept of geography. It only sees "X employees needed from 08:00-09:00". But home care includes travel time. CAIRE solves this through iterative learning:

  1. Bootstrap (First Run): Estimate travel from GPS coordinates (average distance, urban speed model)
  2. Iterative (Each Run): FSR reveals actual travel → ESS adjusts demand → Converges in 2-3 iterations
  3. Learned (After 5+ Runs): System builds efficiency profiles per service area/hour → Future runs converge in 1 iteration
FSR: Field Service Routing Engine

What is FSR?

Field Service Routing (FSR) solves the Vehicle Routing Problem with Time Windows (VRPTW) for home care. Given employees with shifts, FSR determines which employee visits which client and optimizes routes.

Core Functionality

  • Input: Employees (vehicles) with shifts, visits (jobs) with time windows and locations
  • Output: Visit-to-employee assignments, visit sequence per employee, travel times, efficiency metrics
  • Optimization Goals: Minimize travel time, maximize continuity, balance workload

Optimization Objectives (Weighted)

Objective Weight Description
Continuity 40% Prefer employees who visited this client before
Travel Time 30% Minimize total travel distance/time
Workload Balance 20% Even distribution across employees
Shift Utilization 10% Maximize service time vs empty hours

Continuity Focus: FSR prioritizes client-caregiver relationships (40% weight). Target: <10-15 different caregivers per client per 14 days. This builds trust and familiarity.

Pinning Mechanics

FSR supports hybrid schedules with both fixed and flexible visits:

Pinned Visits (Fixed)

Locked assignments from approved slingor. Cannot be moved by FSR.

Unpinned Visits (Flexible)

New or movable visits. FSR can optimize freely.

Use Cases: Stable days use pinned visits (70-90% of schedule). New slingor start fully unpinned. Daily disruptions unpin only affected visits.

From-Patch API (Incremental Optimization)

Two FSR modes for different scenarios:

Mode Use Case Performance
Full Solve New slinga creation, weekly planning 2-4 minutes (45 visits, 9 employees)
From-Patch Adding 1-2 visits to existing schedule, real-time disruptions 30-60 seconds (inherits previous solution)

Performance Characteristics

  • 45 visits, 9 employees: 60-120 seconds
  • 100 visits, 20 employees: 2-4 minutes
  • 200 visits, 40 employees: 5-8 minutes
  • Optimization strategy: Metaheuristics (simulated annealing, tabu search)
Mobile Actuals Integration & Learning

The Learning Loop

As caregivers use the mobile app to check in/out of visits, CAIRE learns actual travel patterns and improves accuracy automatically.

graph LR APP[Mobile App] -->|Check-in 08:05| DB[Actuals Database] DB -->|Analyze Delta| CALC[+5 min vs planned] CALC -->|Update| PROFILE[Travel Profile] PROFILE -->|Overhead: 1.28x → 1.30x| NEXT[Next ESS Run] NEXT -->|Uses learned data| FAST[Faster Convergence] style APP fill:#22C55E,color:#fff style PROFILE fill:#9333EA,color:#fff style FAST fill:#14B8A6,color:#fff

Multi-Source EVV (Electronic Visit Verification)

CAIRE mobile app supports multiple check-in methods (priority order):

  1. Phoniro - Smart lock system (official billing record in municipalities like Nacka)
  2. NFC - Physical tag verification at client location
  3. GPS - Geofence verification (100m radius default)
  4. Manual - Fallback when offline or no hardware

What Gets Learned

  • Service area overhead: Travel multiplier per geographic area (Huddinge: 1.28x, Nacka: 1.45x)
  • Hour-of-day patterns: Morning rush vs afternoon calm
  • Day-of-week patterns: Monday (busy) vs Friday (lighter)
  • Employee-specific patterns: Some caregivers consistently faster/slower

Convergence Improvement Over Time

Stage Iterations Time Confidence
First optimization 3 8 minutes Manual geographic estimate
After 5 runs 2 5 minutes Medium (learned profile)
After 20 runs 1 3 minutes High (auto-pilot)

Key Insight: Manual slingor represent years of accumulated knowledge about travel patterns. CAIRE learns this in days, not years, and updates automatically as conditions change.

Offline Mode

Mobile app works without internet connection:

  • Local database: WatermelonDB (SQLite wrapper) with encrypted PII
  • Sync strategy: Download 7 days of visits on app open, queue mutations when offline
  • Auto-sync: Queued actions sync within 30 seconds of reconnection
Technical Glossary

Core Concepts

ESS (Employee Shift Scheduling)
Optimization model that determines who works when and on which shifts, based on demand curves and labor law constraints.
FSR (Field Service Routing)
Optimization model that assigns visits to employees and sequences them into routes, minimizing travel time.
Convergence
State where ESS estimated overhead matches FSR actual overhead within tolerance (typically ±5%). Indicates optimization is complete.
Demand Curve
Hourly breakdown of how many employees are needed per time slot (e.g., 08:00-09:00: 9 employees). Input to ESS.
Travel Overhead
Multiplier applied to service hours to account for travel time. Example: 1.35x means 35% additional time needed beyond service hours.
Pinning
Marking a visit as "fixed" so FSR cannot move it to a different employee or time. Used to preserve approved slinga patterns.
Kollektivavtal
Swedish collective bargaining agreements that define labor law rules (max hours, rest periods, overtime rates). Automated in CAIRE ESS.
Timefold
Commercial optimization solver used by CAIRE for both ESS and FSR models. Cloud API-based (no local compute).
VRPTW (Vehicle Routing Problem with Time Windows)
Mathematical problem class that FSR solves. NP-hard complexity. Each employee is modeled as a "vehicle" that travels between "jobs" (visits).
Actuals
Real-world execution data captured by mobile apps (check-in times, check-out times, actual duration). Contrasts with "planned" data.
EVV (Electronic Visit Verification)
Digital check-in/check-out systems (Phoniro, NFC, GPS) that record actual visit times. Used to verify care delivery and learn travel patterns.
From-Patch
FSR API mode that inherits a previous solution and only re-optimizes changed visits. Faster than full solve (30-60 seconds vs 2-3 minutes).
Slinga
Swedish term for recurring weekly schedule pattern. Example: "Huddinge Västra Monday slinga" defines the standard Monday schedule for that area.
API Integration & Data Flow

GraphQL API

CAIRE exposes a GraphQL API for optimization operations:

mutation StartTwoPhaseOptimization($input: TwoPhaseOptimizationInput!) { startTwoPhaseOptimization(input: $input) { essMetrics { activatedEmployees fixedEmployees hourlyEmployees totalShiftCostSek } fsrMetrics { totalTravelMinutes assignedVisits unassignedVisits } combinedMetrics { trueEfficiency costPerVisit continuityScore } convergenceInfo { converged iterations travelOverheadLearned } } }

Database Schema (PostgreSQL)

Key tables for ESS+FSR optimization:

  • TravelProfile: Learned overhead per service area per hour
  • OptimizationMetrics: Combined ESS+FSR KPIs per solution
  • EmployeeClientAffinity: Continuity tracking (visit history)
  • Visit: Core visit data with actuals (actualStartTime, actualEndTime, checkInSource)

File Locations (Codebase)

  • apps/dashboard-server/src/services/timefold/ESSClient.ts - ESS API client
  • apps/dashboard-server/src/services/timefold/ess.types.ts - TypeScript types
  • apps/dashboard-server/src/services/bridge/mappers/db-to-ess.mapper.ts - Data mapper
  • apps/dashboard-server/src/services/bridge/scheduling/demand-curve.service.ts - Demand generation
  • packages/graphql/operations/mutations/startTwoPhaseOptimization.graphql - GraphQL mutation

Ready to See It in Action?

Try the interactive demo or return to the customer overview

Interactive Demo Customer Overview