Smart Scheduling & Demand Prediction
Relevant source files
The following files were used as context for generating this wiki page:
- backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts
- backend/src/application/use-cases/ai/DemandPredictionUseCase.ts
- backend/src/infrastructure/services/AtlasAIService.ts
- backend/src/interfaces/controllers/AIController.ts
- backend/src/application/use-cases/booking/CreateBookingUseCase.ts
- backend/src/application/use-cases/ai/DynamicPricingUseCase.ts
The Smart Scheduling and Demand Prediction systems provide the operational intelligence for the AtlasCleanAI platform. These components automate cleaner assignments, optimize dispatching, and forecast service needs to ensure efficient workforce utilization and accurate pricing.
Smart Scheduling identifies the best available cleaner for a specific job based on location, skills, and ratings. Demand Prediction analyzes historical and regional factors to forecast future service volume, allowing the platform to adjust capacity and pricing thresholds dynamically. These features integrate directly with the Booking Engine to provide real-time recommendations during the customer checkout process.
Sources: README.md, backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts
System Architecture
The AI intelligence layer operates through specialized Use Cases that interact with the AtlasAIService. This service communicates with an external AI API or falls back to local heuristics if the external service is unavailable.
Component Relationship
The following diagram illustrates how AI use cases interact with core repositories and the infrastructure service.
Smart Scheduling Logic
The SmartSchedulingUseCase manages the selection and validation of cleaners for new bookings. It executes a multi-step process to ensure a cleaner is both available and qualified.
- Availability Filter: The system queries the
CleanerRepositoryfor cleaners matching the requestedTimeSlotandpostalCode. - AI Optimization: The
AtlasAIServiceranks available cleaners based on a combination of skills, ratings, and experience. - Conflict Validation: The system checks the
BookingRepositoryfor any overlapping schedules for the top-ranked cleaner. - Alternative Generation: If conflicts exist, the system calculates alternative start times in 15-minute increments.
Sources: backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts:22-48
Cleaner Scoring Heuristics
When the external AI API is unavailable, the AtlasAIService uses the following local scoring logic:
| Factor | Weight/Boost | Criteria |
|---|---|---|
| Skill Match | +0.25 | Cleaner skills match the requested serviceType |
| Local Area | +0.20 | Requested postalCode is in the cleaner's serviceAreas |
| Experience | Up to +0.20 | Calculated as completedJobs / 200 |
| Rating | Up to +1.00 | Based on the cleaner's 5-star rating scale |
Sources: backend/src/infrastructure/services/AtlasAIService.ts:71-80
Demand Prediction
DemandPredictionUseCase forecasts service demand for a specific region and service type over a given time horizon.
Data Flow for Prediction
The system generates a demandScore (0.0 to 1.0). If the score exceeds 0.8, it recommends increasing cleaner availability and surge pricing thresholds.
Sources: backend/src/infrastructure/services/AtlasAIService.ts:95-102
Dynamic Pricing Integration
AI-driven scheduling works in tandem with DynamicPricingUseCase. Pricing is adjusted based on service duration, "rush hour" timing, and weekend multipliers.
Pricing Calculation Factors
- Base Rate: Determined by
serviceType(e.g., Standard: $80, Commercial: $250). - Time Multipliers: Weekend starts apply a 1.15x multiplier. "Rush hour" (7-9 AM, 5-7 PM) adds a 1.12x multiplier via
AtlasAIService. - Extras: Flat fee per additional item (e.g., $15 per extra).
Sources: backend/src/application/use-cases/ai/DynamicPricingUseCase.ts:20-33, backend/src/infrastructure/services/AtlasAIService.ts:117-125
API Endpoints
The AIController exposes the following endpoints for internal and operational use:
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/v1/ai/predict-demand | GET | postalCode, serviceType, horizonDays | Forecasts demand score and recommendations. |
/api/v1/ai/smart-scheduling | POST | postalCode, serviceType, start, end | Returns recommended cleaner and alternative slots. |
/api/v1/ai/dynamic-pricing | POST | address, serviceType, scheduledStart, scheduledEnd | Calculates the total price with AI multipliers. |
Sources: backend/src/interfaces/controllers/AIController.ts:15-75, backend/src/app.ts:223
Conclusion
Smart Scheduling and Demand Prediction form the core of AtlasCleanAI's operational efficiency. By combining real-time availability checks with AI-driven scoring and forecasting, the platform reduces manual dispatching effort and optimizes pricing based on market demand. This ensures that the most qualified cleaners are assigned to jobs while maintaining high service availability in high-demand areas.