Workforce & Cleaner Management
Relevant source files
The following files were used as context for generating this wiki page:
Workforce & Cleaner Management handles the lifecycle, availability, and optimization of cleaning professionals within the AtlasCleanAI platform. This system manages cleaner profiles, tracks skills and service areas, and determines real-time availability for job assignments.
The module integrates with the AI Intelligence Layer to rank and recommend cleaners based on performance metrics such as ratings and completed jobs. It ensures that service requests are matched with qualified personnel who meet specific geographic and schedule requirements.
Sources: README.md:143-157, backend/src/app.ts:71-125
Cleaner Data Model
The system defines a Cleaner entity containing professional attributes, performance metrics, and operational constraints.
Cleaner Properties and Schema
The following table describes the data structure for a cleaner:
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the cleaner. |
firstName/lastName | String | Legal name of the professional. |
rating | Float | Average performance score (default 5.0). |
completedJobs | Integer | Total number of successfully finished assignments. |
skills | String[] | List of service types (e.g., standard, deep, commercial). |
serviceAreas | String[] | List of postal codes the cleaner serves. |
availability | Json/Array | Weekly schedule windows with day, start, and end hours. |
backgroundChecked | Boolean | Verification status for security compliance. |
Sources: backend/src/domain/entities/Cleaner.ts:5-24, backend/src/infrastructure/database/prisma/schema.prisma:73-89
Entity Relationships
The cleaner entity relates to bookings, reviews, and the core user system for authentication.
The diagram shows that a Cleaner can have multiple Bookings and Reviews, and optionally links to a User record.
Sources: backend/src/infrastructure/database/prisma/schema.prisma:73-138
Availability and Scheduling
The system determines availability by matching requested time slots against a cleaner's defined working windows and existing booking conflicts.
Availability Logic
The isAvailable method in the Cleaner entity validates if a specific TimeSlot falls within the cleaner's CleanerAvailability profile. It checks the day of the week and compares UTC hours for the start and end of the slot.
Sources: backend/src/domain/entities/Cleaner.ts:54-62
Smart Scheduling Flow
When a booking is requested, the system filters available cleaners and uses AI to rank them.
The flow describes how SmartSchedulingUseCase utilizes ICleanerRepository to find candidates before passing them to AtlasAIService.
Sources: backend/src/application/use-cases/ai/SmartSchedulingUseCase.ts:22-48
AI-Powered Recommendations
The CleanerRecommendationUseCase and AtlasAIService optimize workforce allocation by scoring cleaners based on specific request parameters.
Scoring Heuristics
If the external AI API is unavailable, the system applies local heuristics to rank cleaners:
- Skill Match: 0.25 boost if skills include the service type.
- Area Match: 0.20 boost if the postal code is in the service areas.
- Experience: Up to 0.20 boost based on the number of completed jobs (capped at 200).
- Rating: Up to 1.0 boost based on the cleaner's 5-star rating.
Sources: backend/src/infrastructure/services/AtlasAIService.ts:63-74
Recommendation API
The CleanerController and AIController expose endpoints to query the workforce.
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/v1/cleaners | GET | start, end, postalCode | Lists available cleaners for a slot. |
/api/v1/ai/recommend-cleaner | POST | serviceType, postalCode, start, end | Returns the top-ranked cleaner. |
Sources: backend/src/interfaces/controllers/CleanerController.ts:11-20, backend/src/interfaces/controllers/AIController.ts:74-90
Implementation Example
The following snippet demonstrates how a cleaner is instantiated with specific availability and skills:
// backend/src/app.ts:74-88
new Cleaner({
id: '00000000-0000-0000-0000-000000000101',
firstName: 'Maya',
lastName: 'Santos',
email: 'maya.santos@atlasclean.ai',
rating: 4.9,
completedJobs: 243,
skills: ['standard', 'deep', 'moveout'],
serviceAreas: ['94107', '94110', '94158'],
availability: [
{ dayOfWeek: 1, startHour: 8, endHour: 18 },
{ dayOfWeek: 2, startHour: 8, endHour: 18 },
],
vehicleAvailable: true,
backgroundChecked: true,
createdAt: new Date(),
updatedAt: new Date(),
})
Sources: backend/src/app.ts:74-88
Workforce management ensures service quality by combining strict entity validation with AI-driven optimization, allowing the platform to assign the most suitable professional to every customer request.