Authentication Service and State Management in SailPilot
========================================================

The `auth_service.dart` file defines the `AuthService` class and the `AuthState` class which together manage the user authentication lifecycle and state within the SailPilot application.

AuthService
-----------

The `AuthService` class provides functionality for user registration, login, and token management. It interacts with the backend server to authenticate users and securely stores tokens using `FlutterSecureStorage`.

- **register**: Handles user registration and stores user details and tokens securely.
- **login**: Authenticates the user and retrieves tokens if the device is online. If offline, it validates the user credentials locally.
- **logout**: Clears the user session and navigates the user to the sign-in screen.

For more information on how token management plays a role in data synchronization, see :ref:`token-handling-section`.

AuthState
---------

The `AuthState` class is a state management solution that monitors and updates the authentication state throughout the app. It uses the `ChangeNotifier` mixin to notify listeners of authentication state changes.

- **login**: Sets the user as logged in and starts the token refresh and data synchronization processes.
- **logout**: Logs out the user, stops the token refresh and data sync, and updates the UI accordingly.
- **startTokenRefreshTask**: Initiates a periodic task to refresh the access token, ensuring the user session remains valid.
- **stopTokenRefreshTask**: Cancels the periodic token refresh task, typically called during logout.

Both classes are crucial for maintaining a secure and uninterrupted user experience in SailPilot, particularly in handling scenarios where network connectivity is intermittent.

.. note:: This documentation should be included in a section like `frontend/auth_flow` to provide a comprehensive guide to the authentication process in the application.