User Authentication Flow in the Frontend v2.0.0

[Dynavy]

Discussion: Full Authentication Flow Implementation

Summary

This flow covers the entire process for login, registration (step one and step two), handling API communication, token extraction and storage, error handling, and UI updates based on the changes in the AuthState. The implementation follows the MVVM (Model-View-ViewModel) architecture to ensure clean separation of concerns, scalability, and maintainability.

This process was initially introduced in version v1.0.0, as discussed in a previous post about the authentication flow. However, this version has seen considerable improvements, including refined API communication, enhanced response handling, robust error management, and a more structured approach to UI updates via AuthState. Additionally, new components have been introduced for user data extraction and session management, making the overall authentication flow even more robust and maintainable.

---

Detailed Breakdown of the Implementation

1. User Interface (UI Layer)

• Screens:
  The UI layer includes the LoginScreen, RegisterStepOneScreen, and RegisterStepTwoScreen. These screens are responsible for gathering the necessary user inputs.

• Frontend Validation:
  Upon data entry, the screens validate the inputs. If the data is correct, the authentication process is initiated; otherwise, appropriate error messages are displayed.

• Error Display:
  Validation failures trigger error messages in the UI to inform the user of any issues with the input.

---

2. AuthViewModel (ViewModel Layer for Authentication)

• Invoking Auth Methods:
  After successful frontend validation, the AuthViewModel invokes the necessary authentication methods via the UserRepository. This delegation ensures that business logic remains outside the ViewModel.

• Updating AuthState:
  The AuthViewModel receives a response from the UserRepository in the form of an AuthState—indicating either success or error. The UI observes this state (using mechanisms like LaunchedEffect in Compose) to provide real-time feedback, displaying success, error, or loading states as needed.

• Integrating User Data Extraction:
  When authentication is successful, the AuthViewModel leverages UserService to extract the required JSON fields (such as username, email, token, etc.) from the backend response. With these extracted fields, it calls UserSession.setUser(...) to create and store a user instance.

---

3. UserRepository (Repository Layer)

• Calling AuthService Methods:
  The UserRepository acts as an intermediary between the AuthViewModel and the AuthService. It invokes the appropriate methods in the AuthService for login or registration.

• Token Extraction & Error Handling:
  On receiving a successful response from the AuthService, the repository extracts the authentication token. In case of errors, it extracts the error message from the response and incorporates it into the AuthState, which is then observed by the AuthViewModel.

• Session Storage:
  On a successful authentication, the token is securely stored (for example, in a DataStoreManager), and the user data is updated via UserService and UserSession.

---

4. Service Layer

AuthService

• Making API Requests:
  Responsible for making the actual API requests to the backend, using appropriate DTOs to ensure that correct data and tokens are sent.

• Handling API Responses:
  Once the backend responds, AuthService maps the response to the appropriate DTO. If an authentication token is present, it is extracted and returned to the UserRepository.

• ApiService Interface Implementation:
  By implementing the ApiService interface, the AuthService ensures that API communication is decoupled from the rest of the application logic, which improves testability and maintainability.

UserService

• Extracting User Data:
  Upon a successful authentication response, the UserService extracts the necessary fields from the JSON response. This may include username, email, token, and any other relevant data.

• Triggering Session Updates:
  With the extracted data, UserService calls UserSession.setUser(...) to create an instance of the User and store it for later use. This user instance is then made available to the UI through a dedicated UserViewModel.

---

5. Session Management and UserViewModel

UserSession

• Source of Truth:
  UserSession serves as the central repository for the authenticated user's data and tokens. It stores this information in memory and persists it securely (using mechanisms such as DataStoreManager or encrypted storage).

• Global Access:
  Any component that needs user information—be it services or ViewModels—accesses it through UserSession.

UserViewModel

• Exposing User Data:
  A dedicated UserViewModel is responsible for exposing the user data stored in UserSession to the UI.

Example of displaying the stored data in the Screens:

val userViewModel: UserViewModel = hiltViewModel()
val user by userViewModel.user.collectAsState()
val username = user?.username ?: "Username"

This allows any extracted field (like username, email, phone number,etc...) to be accessed in any Screen.

---

Flow Explanation

1. UI Layer: The flow begins when the user interacts with the login or registration screen. The UI validates the input data to ensure that all necessary fields are correctly filled before proceeding with the real authentication trough the backend.

2. ViewModel Layer: Once the inputs are validated, the AuthViewModel calls the necessary authentication methods via the AuthViewModel. It waits for the response from the UserRepository.

3. Repository Layer: The UserRepository communicates with the AuthService to make the API call to the backend. It processes the response by extracting the token or error message and passes it back to the AuthViewModel.
   If the token is extracted successfully, it gets saved on the frontend via the DataStoreManager.

4. Service Layer: The AuthService makes the API request using the appropriate DTOs and ensures the correct tokens are attached. It processes the response from the backend and returns the result to the UserRepository.
   Upon success, UserService extracts the JSON fields from the response and calls UserSession.setUser(...) to update the session.

5. Session Management: UserSession holds the authenticated user's data, which is then observed by the UserViewModel.

6. Response Handling: Once the response is processed by the UserRepository, it updates the AuthState and returns it to the AuthViewModel.

7. UI Update: The AuthViewModel observes the updated AuthState and updates the UI, which may display success, error, or loading states based on the result.
   The UserViewModel has the responsability to display the user stored data in the screens.

Enhancements Made

Separation of Concerns

• Authentication logic is handled in AuthViewModel and UserRepository.
• API communication is encapsulated within AuthService.
• User data extraction is managed by UserService.
• Session management is handled through UserSession and UserViewModel.

This clear division ensures a clean and maintainable codebase.

Robust Error Handling

• Errors from the backend are captured and propagated through AuthState.
• The UI is able to display precise and meaningful backend custom error messages.

Interface Implementation

• AuthService implements the ApiService interface.
• This provides a clear contract for backend communication and enhances testability.

Real-time UI Feedback

• Utilizes reactive streams (e.g., StateFlow) and Compose’s LaunchedEffect.
• The UI responds immediately to authentication state changes.

User Session Integration

• Centralized user data is maintained via UserSession and exposed through UserViewModel.
• Ensures consistent access to user data across different screens.

---

Related Links

• State Management (Jetpack Compose + StateFlow): State Management (Jetpack Compose + StateFlow) #63

• User Register flow in Backend: User Registration flow v2.0.0 copay-app-backend#97

• User Login flow in Backend: User Login Flow copay-app-backend#38

• AuthController Validation and Exceptions Flow in Backend: AuthController Validation and Exceptions Flow copay-app-backend#49

---

Mermaid Diagram

[poksyy]

It looks spectacular. Can you check that everything is working properly? @Dynavy

[Dynavy]

Everything is working perfectly!

[Dynavy]

08/04/2025
Discussion updated with the new layers (UserService, UserSession and UserViewModel).

@poksyy, @krschan