phone_login/DESIGN.md

# DESIGN.md

## 1. Overview

This document outlines the design for a simple Flutter application featuring phone number-based authentication, integrating a smart home dashboard interface. The application, named "phone login," will provide a seamless user experience for both logged-in and logged-out states, with clear pathways for phone number input, SMS verification, and user profile management. The UI design will adhere to modern Flutter best practices, focusing on clarity, responsiveness, and user-friendliness.

## 2. Detailed Analysis of the Goal or Problem

The primary goal is to create a functional and aesthetically pleasing Flutter application that handles user authentication via phone number and displays different home screen layouts based on the user's login status.

**Key features and screens identified from the provided images:**

*   **Logged-out Home Screen (`home_logout.png`):**
    *   Displays app branding ("SmartLink" logo).
    *   Features a welcoming message and a generic smart home illustration.
    *   Provides clear calls to action: "Get Started / Login" and "View Demo."
    *   Includes a bottom navigation bar with "Home" and "Profile" (though "Profile" might be inaccessible or redirect to login when logged out).
*   **Phone Number Input Screen (`phone_number.png`):**
    *   A dedicated screen for users to enter their phone number.
    *   Includes a country code selector (e.g., dropdown or modal).
    *   A prominent input field for the phone number.
    *   A "Next" button to proceed.
    *   Links to "Terms of Service" and "Privacy Policy."
*   **SMS Verification Screen (`sms_ver.png`):**
    *   Follows the phone number input screen.
    *   Requires the user to enter a 6-digit verification code received via SMS.
    *   Clear instructions and indication of the number the code was sent to.
    *   Input fields for the 6-digit code.
    *   A "Verify" button.
    *   A "Resend Code" option, likely with a countdown.
*   **Logged-in Home Screen (`home_login.png`):**
    *   Displays a personalized welcome message (e.g., "Welcome back, Alex").
    *   Shows a user profile avatar and notification icon.
    *   Indicates active devices (e.g., "4 devices are currently active").
    *   A grid or list of "Connected Devices" with toggle switches (e.g., Living Room Lamp, Air Purifier, Smart Camera, Thermostat, Main WiFi).
    *   An "Add Device" card.
    *   A bottom navigation bar with "Home" and "Profile."
*   **User Profile Screen (`user_profile.png`):**
    *   Displays user's name, email, and profile picture with an edit option.
    *   An "Edit Profile" button.
    *   Sections for "Preferences" (Account Security, Notification Settings, Privacy & Data).
    *   Sections for "Support" (About Us, Logout).
    *   A bottom navigation bar with "Home" and "Profile."

**Problems to address:**

*   **Secure Phone Authentication:** Implement a robust and secure flow for phone number verification using OTP.
*   **State Management:** Effectively manage the application's state, especially distinguishing between logged-in and logged-out states and handling user data across screens.
*   **Navigation:** Implement clear and intuitive navigation between authentication screens, home screens, and the profile screen, with proper handling of authenticated routes.
*   **UI/UX:** Ensure a visually appealing and responsive interface that matches the provided design images and adheres to Flutter's Material Design principles.
*   **Error Handling:** Implement user-friendly error messages and feedback for network issues, incorrect OTPs, and other potential problems.

## 3. Alternatives Considered

For phone number authentication, several approaches exist, primarily differentiating by the backend service used for sending SMS and verifying OTPs.

*   **Firebase Authentication (with Phone Number Provider):**
    *   **Pros:** Fully managed, cross-platform, integrates well with other Firebase services, often has a generous free tier. Handles OTP generation, sending, and verification.
    *   **Cons:** Requires Firebase project setup and dependency.
*   **Twilio/Auth0/Custom Backend with SMS Gateway:**
    *   **Pros:** Maximum flexibility and control over the authentication flow and data. Allows for custom backend logic and integration with existing systems.
    *   **Cons:** Higher development effort, responsible for security, scaling, and maintenance of the backend infrastructure. Requires integrating with an SMS gateway API (e.g., Twilio, Nexmo).
*   **Local Simulation (for development/demo):**
    *   **Pros:** Quickest to get started, no backend required for initial UI development.
    *   **Cons:** Not suitable for production, lacks real authentication security.

**Decision:** Given the "simple phone login app" requirement and the desire for a robust solution, **Firebase Authentication** is the preferred choice. It simplifies the backend aspects significantly, allowing focus on the Flutter frontend development while providing a secure and scalable authentication service.

For state management, we will prioritize Flutter's built-in solutions for simpler cases (e.g., `ValueNotifier`, `ChangeNotifier`) and consider `Provider` for app-wide state, adhering to the provided guidelines.

For navigation, `go_router` will be used for declarative routing and deep linking capabilities, aligning with modern Flutter navigation practices.

## 4. Detailed Design for the New Package

The application will follow a layered architecture, separating concerns into presentation, domain, and data layers. This promotes maintainability, testability, and scalability.

**Project Structure (High-Level):**

```
lib/
├── main.dart
├── app.dart              # MaterialApp setup, theme, routing
├── auth/                 # Authentication related screens and logic
│   ├── auth_repository.dart
│   ├── phone_input_screen.dart
│   ├── sms_verification_screen.dart
│   └── auth_state.dart   # Notifier for authentication state
├── home/                 # Home screen (logged-in/logged-out)
│   ├── home_screen.dart
│   └── widgets/          # Home screen specific widgets
├── profile/              # User profile screen
│   ├── profile_screen.dart
│   └── widgets/          # Profile screen specific widgets
├── services/             # Backend services (e.g., Firebase, API clients)
│   ├── firebase_service.dart
│   └── device_service.dart
├── shared/               # Common widgets, utilities, models
│   ├── models/
│   │   ├── user.dart
│   │   └── device.dart
│   ├── widgets/
│   └── constants.dart
└── theme/                # Theming and styling
    └── app_theme.dart
```

**Core Components and Flow:**

1.  **`main.dart`**: Application entry point. Initializes Firebase (if used) and runs `App`.
2.  **`app.dart`**: Configures `MaterialApp.router` with `go_router` for navigation and defines the overall app theme. It will listen to the authentication state to redirect users appropriately.
3.  **Authentication Flow (`auth/`):**
    *   **`AuthRepository`**: An abstract class or interface defining authentication operations (e.g., `signInWithPhoneNumber`, `verifyOtp`, `signOut`).
    *   **`FirebaseAuthService` (in `services/`):** Implementation of `AuthRepository` using Firebase Authentication.
    *   **`PhoneInputScreen`**: UI for entering the phone number. Will handle input validation and trigger OTP sending via `AuthRepository`.
    *   **`SmsVerificationScreen`**: UI for entering the SMS code. Will verify the OTP via `AuthRepository`.
    *   **`AuthState` (e.g., `ChangeNotifier` or `Provider`):** Manages the user's authentication status (logged in, logged out, loading, error). `App` will observe this state to update routing.
4.  **Home Screens (`home/`):**
    *   **`HomeScreen`**: A StatefulWidget that dynamically renders either the `LoggedOutHomeWidget` or `LoggedInHomeWidget` based on the `AuthState`.
    *   **`LoggedOutHomeWidget`**: Corresponds to `home_logout.png`. Contains "Get Started / Login" and "View Demo" buttons. The "Get Started / Login" button will navigate to `PhoneInputScreen`.
    *   **`LoggedInHomeWidget`**: Corresponds to `home_login.png`. Displays user info, device list, and "Add Device" functionality. Interactions with device toggles will be handled by a `DeviceService`.
5.  **User Profile (`profile/`):**
    *   **`ProfileScreen`**: Corresponds to `user_profile.png`. Displays user details and provides options for editing profile, notification settings, privacy, and most importantly, a "Logout" button that interacts with `AuthRepository`.

**State Management:**

*   **Authentication State:** A `ChangeNotifier` (e.g., `AuthState`) will hold the user's authentication status (`User? _currentUser`). `ChangeNotifierProvider` will be used to make this available throughout the app. `go_router` will use a `redirect` listener based on this state.
*   **Ephemeral UI State:** `ValueNotifier` or local `StatefulWidget` state will be used for UI-specific elements like text field controllers, loading indicators, and timers for OTP resend.

**Navigation (`go_router`):**

The `go_router` configuration will define the routes. A `redirect` function will be implemented to handle authentication logic:
*   If the user is logged out and tries to access a protected route (e.g., `/home`, `/profile`), they will be redirected to the phone input screen (`/login`).
*   If the user is logged in and tries to access the login screen, they will be redirected to the home screen.

```dart
// Example go_router configuration snippet
final GoRouter _router = GoRouter(
  redirect: (context, state) {
    // Logic to check AuthState and redirect
    final bool loggedIn = authState.isLoggedIn; // Assuming authState is accessible
    final bool loggingIn = state.matchedLocation == '/login' || state.matchedLocation == '/sms_verify';

    if (!loggedIn && !loggingIn) return '/login';
    if (loggedIn && loggingIn) return '/';
    return null;
  },
  routes: <RouteBase>[
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/login',
      builder: (context, state) => const PhoneInputScreen(),
    ),
    GoRoute(
      path: '/sms_verify',
      builder: (context, state) => const SmsVerificationScreen(),
    ),
    GoRoute(
      path: '/profile',
      builder: (context, state) => const ProfileScreen(),
    ),
  ],
);
```

**UI/UX Considerations:**

*   **Theming:** Centralized `ThemeData` using `ColorScheme.fromSeed` for consistent light/dark mode and component styling, as per Material 3 guidelines. Custom fonts will be managed via `google_fonts` if needed.
*   **Responsiveness:** `LayoutBuilder` and `MediaQuery` will be utilized to ensure layouts adapt to various screen sizes.
*   **Form Validation:** Real-time validation for phone number input, with clear error messages.
*   **Loading States:** Visual feedback (e.g., `CircularProgressIndicator`) for asynchronous operations like sending OTP or verifying codes.
*   **Auto-fill/Auto-read:** Explore using `sms_autofill` or `otp_autofill` packages for seamless OTP entry.
*   **Accessibility:** Semantic labels for interactive elements and testing with dynamic text scaling.

## 5. Diagrams

### Application Flow Diagram (Mermaid)

```mermaid
graph TD
    A[App Startup] --> B{Is User Logged In?};
    B -- No --> C[Logged Out Home (home_logout.png)];
    B -- Yes --> D[Logged In Home (home_login.png)];

    C --> E[Get Started / Login Button];
    E --> F[Phone Number Input (phone_number.png)];
    F --> G[SMS Verification (sms_ver.png)];
    G --> H{SMS Verified?};
    H -- Yes --> I[Set User Session];
    I --> D;
    H -- No --> G;

    D -- "Profile Tab" --> J[User Profile (user_profile.png)];
    J -- "Logout Button" --> K[Clear User Session];
    K --> C;
```

### Authentication Sequence Diagram (Mermaid)

```mermaid
sequenceDiagram
    participant User
    participant App
    participant AuthScreen("Phone Number Input / SMS Verification")
    participant AuthRepo[Auth Repository]
    participant Firebase("Firebase Auth")

    User->>AuthScreen: Enter Phone Number
    AuthScreen->>AuthRepo: Request OTP (phone number)
    AuthRepo->>Firebase: Send OTP
    Firebase-->>AuthRepo: OTP Sent Confirmation
    AuthRepo-->>AuthScreen: OTP Sent, Start Timer
    AuthScreen->>User: Display SMS Input Field

    User->>AuthScreen: Enter SMS Code
    AuthScreen->>AuthRepo: Verify OTP (phone number, code)
    AuthRepo->>Firebase: Verify OTP
    Firebase-->>AuthRepo: Verification Result
    alt OTP Valid
        AuthRepo-->>AuthScreen: Success
        AuthScreen->>App: User Authenticated
        App->>App: Update Auth State (LoggedIn)
        App->>User: Navigate to Logged In Home
    else OTP Invalid
        AuthRepo-->>AuthScreen: Error: Invalid OTP
        AuthScreen->>User: Display Error Message, Allow Retry/Resend
    end

    User->>AuthScreen: Resend Code (after timer)
    AuthScreen->>AuthRepo: Request OTP
    AuthRepo->>Firebase: Resend OTP
```

## 6. Summary of the Design

The "phone login" application will be a Flutter-based smart home management app utilizing Firebase Authentication for secure phone number-based login. The design emphasizes a clear, user-friendly flow through distinct screens for phone input, SMS verification, and both logged-in and logged-out home dashboards. `go_router` will manage navigation with authentication-aware redirects. State management will leverage `ChangeNotifierProvider` for global authentication state and local state for UI elements. The UI will adhere to Material 3 design principles, ensuring consistency, responsiveness, and accessibility.

## 7. References

*   **Flutter Phone Number Authentication Best Practices UI/UX:** [https://www.google.com/search?q=Flutter+phone+number+authentication+best+practices+UI+UX](https://www.google.com/search?q=Flutter+phone+number+authentication+best_practices_UI_UX) (Used for guidelines on phone input, OTP verification, and general UI/UX)
*   **Flutter Theming and Material 3:** [https://docs.flutter.dev/data-and-backend/state-management/options](https://docs.flutter.dev/data-and-backend/state-management/options) (General Flutter development best practices)
*   **Firebase Phone Authentication:** [https://firebase.google.com/docs/auth/flutter/phone-auth](https://firebase.google.com/docs/auth/flutter/phone-auth) (Will be used as primary reference for Firebase implementation)
*   **GoRouter Package:** [https://pub.dev/packages/go_router](https://pub.dev/packages/go_router) (Reference for declarative navigation)