AI Cleaner Recommendations
Relevant source files
The following files were used as context for generating this wiki page:
- backend/src/application/use-cases/ai/CleanerRecommendationUseCase.ts
- backend/src/infrastructure/services/AtlasAIService.ts
- backend/src/interfaces/controllers/AIController.ts
- backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts
- backend/src/domain/entities/Cleaner.ts
- backend/src/infrastructure/database/prisma/schema.prisma
AI Cleaner Recommendations select and rank the most suitable service providers for specific cleaning jobs based on availability, geographic location, and performance metrics. This system integrates the Atlas AI Intelligence Layer with workforce management to optimize service quality and operational efficiency.
The recommendation engine operates through a multi-stage process: it filters available personnel using traditional database queries and then applies AI-driven heuristics or external LLM analysis to score and rank candidates.
Recommendation Architecture
The recommendation logic resides within the CleanerRecommendationUseCase and SmartSchedulingUseCase classes. These components interact with the ICleanerRepository to fetch available cleaners and the AtlasAIService to calculate suitability scores.
Data Flow for Recommendations
The following diagram illustrates how a recommendation request moves from the API controller through the application layers to the AI service.
Technical Implementation
Recommendation Logic
The CleanerRecommendationUseCase initiates the recommendation by validating the cleaner's availability against a specific TimeSlot and postalCode. It then delegates ranking to AtlasAIService.recommendCleaner.
Sources: backend/src/application/use-cases/ai/CleanerRecommendationUseCase.ts:7-16
Scoring Heuristics
If the external AI API is unavailable, AtlasAIService executes local fallback heuristics to rank cleaners. The score is calculated using four weighted factors:
| Factor | Weight/Calculation | Description |
|---|---|---|
| Skill Match | +0.25 | Added if cleaner skills match the requested serviceType. |
| Area Match | +0.20 | Added if the postalCode is in the cleaner's serviceAreas. |
| Experience | Up to 0.20 | Calculated as completedJobs / 200 (capped at 0.20). |
| Rating | rating / 5 | Normalizes the cleaner's 5-star rating to a 0-1 scale. |
Sources: backend/src/infrastructure/services/AtlasAIService.ts:63-83
Service Optimization Flow
The optimizeSchedule method manages the communication with the external Atlas AI API.
Data Models
Recommendations rely on the Cleaner entity and the Booking schema for historical performance data.
Cleaner Entity Attributes
The system uses the following fields from the Cleaner model to determine suitability:
| Field | Type | Role in AI Recommendation |
|---|---|---|
rating | Float | Primary quality indicator for scoring. |
completedJobs | Int | Measures experience level for experience boost. |
skills | String[] | Matches against requested serviceType. |
serviceAreas | String[] | Validates geographic eligibility (Postal Code). |
availability | Json | Determines initial availability via TimeSlot. |
Sources: backend/src/domain/entities/Cleaner.ts:7-22, backend/src/infrastructure/database/prisma/schema.prisma:73-88
API Endpoints
The system exposes recommendations via the AI Controller.
POST /api/ai/recommend-cleaner
Returns the single best cleaner recommendation for a given slot.
Parameters:
postalCode(String): The location of the service.serviceType(String): The type of cleaning (e.g., "standard", "deep").start(Date): Requested start time.end(Date): Requested end time.
Sources: backend/src/interfaces/controllers/AIController.ts:66-83
POST /api/ai/smart-scheduling
Returns a ranked list of all eligible cleaners and provides alternative time slots if conflicts exist.
Response Structure:
recommendedCleanerId: ID of the top-ranked cleaner.confidence: The numerical score of the recommendation.rankedCleaners: Full list of candidates with scores and reasons.alternativeSlots: Suggested times offset by 15, 30, or 45 minutes.
Sources: backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts:21-43
Summary
AI Cleaner Recommendations optimize workforce assignment by combining hard constraints (availability, location) with soft scoring (skills, ratings, experience). The system ensures reliability by providing local heuristic fallbacks when external AI services are unreachable, maintaining continuous operational dispatching.