Scheduling architecture for real home care

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

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

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

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

Traditional schedulers only optimize routes for pre-defined shifts. But how do you know how many employees you need? Using Caire Core routing layer 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." Caire Core routing layer does not decide how many shifts to create; it routes visits to shifts you already defined. Caire Core shift layer+Caire Core routing layer avoids this: Caire Core shift layer is demand-driven and creates exactly the shifts needed; Caire Core routing layer 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:

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

Employee Shift Scheduling (Caire Core shift layer) 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.

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

• 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

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

Caire Core shift layer 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

Caire Core shift layer prioritizes fixed-contract employees (zero activation cost) over hourly staff (500 SEK activation cost):

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

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

The Critical Bridge: Caire Core shift layer 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:

• Bootstrap (First Run): Estimate travel from GPS coordinates (average distance, urban speed model)
• Iterative (Each Run): Caire Core routing layer reveals actual travel → Caire Core shift layer adjusts demand → Converges in 2-3 iterations
• Learned (After 5+ Runs): System builds efficiency profiles per service area/hour → Future runs converge in 1 iteration

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

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

• 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

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

Caire Core routing layer supports hybrid schedules with both fixed and flexible visits:

Locked assignments from approved slingor. Cannot be moved by Caire Core routing layer.

New or movable visits. Caire Core routing layer 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.

Two Caire Core routing layer modes for different scenarios:

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

• 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)

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

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

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

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

• 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

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.

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

Caire Core shift layer (Employee Shift Scheduling) Optimization model that determines who works when and on which shifts, based on demand curves and labor law constraints. Caire Core routing layer (Field Service Routing) Optimization model that assigns visits to employees and sequences them into routes, minimizing travel time. Convergence State where Caire Core shift layer estimated overhead matches Caire Core routing layer 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 Caire Core shift layer. 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 Caire Core routing layer cannot move it to a different

CAIRE exposes a GraphQL API for optimization operations:

Key tables for Caire Core shift layer+Caire Core routing layer optimization:

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

apps/dashboard-server/src/services/timefold/ESSClient.ts - Caire Core shift layer 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

• apps/dashboard-server/src/services/timefold/ESSClient.ts - Caire Core shift layer 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

Try the interactive demo or return to the customer overview