Cleaner Application (Flutter)

The Cleaner Application is a Flutter-based mobile platform used by field cleaners to manage their schedules, job assignments, and operational workflows. It serves as one of the primary client-facing interfaces in the AtlasCleanAI Enterprise ecosystem, enabling real-time interaction with the centralized booking and workforce management systems.

Cleaners use this application to view completed jobs, manage availability, and navigate to service areas. The application integrates with shared internal packages to ensure consistency in design and API communication across the enterprise suite.
Sources: README.md:9-11, README.md:162-166, apps/cleaner_app/pubspec.yaml:2-3

Architecture and Dependencies

The application uses a modular architecture supported by several industry-standard Flutter libraries and shared local packages. It follows a BLoC (Business Logic Component) pattern for state management and utilizes a shared design system for UI consistency.

Core Dependencies

The application relies on the following key dependencies for its operations:

• State Management: flutter_bloc and equatable manage application states and business logic.
• Networking: dio and retrofit handle RESTful API communication.
• Navigation: go_router manages declarative routing within the app.
• Storage: flutter_secure_storage stores sensitive authentication tokens, while shared_preferences handles local settings.
• Maps & Location: google_maps_flutter provides geospatial capabilities for job locations.
• Notifications: firebase_messaging enables real-time push notifications for new job assignments.

Sources: apps/cleaner_app/pubspec.yaml:12-32

Shared Packages

The application consumes shared packages located in the packages/ directory to maintain architectural alignment:

• atlas_design_system: Provides brand colors, typography tokens, and pre-styled widgets (buttons, cards, text fields).
• atlas_api_client: Handles standard JSON parsing, error handling, and authenticated requests using bearer tokens.

Sources: README.md:126-139, packages/atlas_design_system/pubspec.yaml

Data Models and State

The application interacts with data structures defined in the backend domain but represented locally for cleaner operations. The primary entity is the Cleaner, which contains profile, performance, and availability data.

Cleaner Profile Structure

Sources: backend/src/domain/entities/Cleaner.ts:7-24, backend/src/infrastructure/database/prisma/schema.prisma:64-77

Logic Flow: Availability Validation

The application must validate if a cleaner is available for a specific TimeSlot before job assignment.

The logic checks the dayOfWeek, startHour, and endHour within the cleaner's availability profile.
Sources: backend/src/domain/entities/Cleaner.ts:58-65

API Integration

The application communicates with the backend via a specialized CleanerController. It retrieves job lists and filters available cleaners based on geospatial and temporal parameters.

Service Interactions

The application calls the list endpoint to fetch either all cleaners or those available within a specific time range and postal code.
Sources: backend/src/interfaces/controllers/CleanerController.ts:11-25, backend/src/app.ts:200

Features and Capabilities

The Cleaner App provides specific functionality to support field operations:

• Job Management: Viewing assigned, in-progress, and completed bookings.
• Scheduling: Updating availability windows which are stored as JSON in the database.
• Geospatial Routing: Using google_maps_flutter to identify service areas and job locations.
• Real-time Updates: Receiving push notifications via Firebase when a booking status changes to ASSIGNED.
• UI Feedback: Utilizing shimmer for loading states and lottie for interactive animations.

Sources: apps/cleaner_app/pubspec.yaml:27-31, backend/src/infrastructure/database/prisma/schema.prisma:41-48, backend/src/domain/entities/Cleaner.ts:16-18

Operational Flow

Cleaners transition through various states during their lifecycle in the platform, managed via the UserStatus and BookingStatus enumerations.

The Cleaner Application serves as the essential tool for service delivery, ensuring that field personnel are synchronized with the AI-powered scheduling and dispatching core of the AtlasCleanAI Enterprise platform.