Customer Application (Flutter)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/customer_app/pubspec.yaml
• packages/atlas_design_system/pubspec.yaml
• README.md
• backend/src/infrastructure/database/prisma/schema.prisma
• backend/src/app.ts
• backend/src/interfaces/controllers/BookingController.ts

The Customer Application is a Flutter-based mobile platform that enables users to book and manage cleaning services within the AtlasCleanAI Enterprise ecosystem. It provides an interface for service selection, scheduling, and payment processing while integrating with centralized AI services for pricing and cleaner recommendations.

The application functions as a client within a broader monorepo architecture, utilizing shared Dart packages for consistent API communication and design language. It interacts primarily with the Node.js backend to facilitate the booking lifecycle and secure user authentication.
Sources: README.md:1-20, apps/customer_app/pubspec.yaml

Application Architecture

The application follows a modular architecture, leveraging the flutter_bloc package for state management and get_it for dependency injection. It uses go_router for declarative navigation and dio combined with retrofit for type-safe REST API communication.

Core Dependencies

The application relies on several specialized libraries to handle mobile-specific features:

Dependency	Purpose
google_maps_flutter	Handles location selection and address visualization.
flutter_stripe	Manages secure payment processing and tokenization.
firebase_messaging	Receives push notifications for booking updates.
flutter_secure_storage	Stores sensitive data like JWT access and refresh tokens.
atlas_design_system	Provides shared UI tokens, themes, and branded components.

Sources: apps/customer_app/pubspec.yaml:13-35, packages/atlas_design_system/pubspec.yaml:1-15

Data Communication Flow

The application communicates with the backend API (defaulting to port 3000 locally) using a shared API client. All requests requiring authentication include short-lived bearer tokens managed via a refresh token flow.

The diagram shows the flow from the Flutter UI through the BLoC state layer to the backend services.
Sources: README.md:22-38, apps/customer_app/pubspec.yaml:15-22

Booking Lifecycle

Customers initiate the booking process by selecting a service type, address, and time slot. The application coordinates with the backend's BookingController and AI services to provide dynamic pricing and cleaner assignments.

Booking Process Flow

1. Service Selection: The user selects a service category (e.g., standard, deep, or move-out).
2. Scheduling: The user chooses a TimeSlot comprising a start and end time.
3. AI Integration: The backend DynamicPricingUseCase calculates a price based on demand and service type, while SmartSchedulingUseCase recommends a cleaner.
4. Confirmation: The user confirms the booking, changing the status from PENDING to ASSIGNED or CONFIRMED.

The sequence diagram illustrates the interaction between the application, the controller, and AI services during a booking request.
Sources: backend/src/app.ts:114-125, backend/src/interfaces/controllers/BookingController.ts:20-31, backend/src/infrastructure/database/prisma/schema.prisma:73-102

Data Models and Schemas

The application interacts with several core entities defined in the backend persistence layer. The following table describes the primary fields involved in customer operations:

Entity	Field	Type	Description
User	role	UserRole	Set to CUSTOMER for app users.
Booking	status	BookingStatus	Tracks lifecycle: PENDING, CONFIRMED, COMPLETED, etc.
Booking	address	Json	Stores line1, city, state, and postal code.
Payment	status	PaymentStatus	Tracks transaction state: AUTHORIZED, SUCCEEDED, FAILED.
Service	basePrice	Decimal	The starting price before AI dynamic adjustments.

Sources: backend/src/infrastructure/database/prisma/schema.prisma:34-135

UI and Design System

The application consumes the atlas_design_system package to ensure brand consistency across all enterprise mobile clients. This package contains:

• Theme Definitions: Standardized Material 3 themes for both Light and Dark modes.
• Branded Components: Pre-styled buttons, cards, and input fields.
• Typography Tokens: Consistent font scales and weights.
• Animations: Integration with lottie for interactive loading and success states.

Sources: packages/atlas_design_system/pubspec.yaml, apps/customer_app/pubspec.yaml:32-34

Security and Authentication

The application implements secure communication using a dual-token strategy. Access tokens are short-lived, while refresh tokens are used to obtain new sessions without requiring the user to re-enter credentials.

• Encryption: Sensitive tokens are stored in flutter_secure_storage, which utilizes Keychain (iOS) and Keystore (Android).
• Rate Limiting: The application respects apiRateLimiter headers from the backend to prevent abuse.
• Auth Middleware: All booking and payment endpoints require a valid JWT via the createAuthMiddleware.

Sources: backend/src/app.ts:153-178, apps/customer_app/pubspec.yaml:23-24

Summary

The Customer Application is a sophisticated Flutter client that integrates deeply with the AtlasCleanAI Enterprise backend. By utilizing shared packages and AI-driven services, it provides customers with a seamless experience for scheduling, real-time pricing, and secure payments, supported by a scalable mobile architecture.