docs: update README with comprehensive project documentation

- Add detailed description of the phone login app
- Document key features including Firebase authentication
- Explain the project architecture and structure
- Add installation and usage instructions
- Include information about dependencies and best practices
- Provide comprehensive documentation for developers

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -1,16 +1,109 @@
 # Phone Login
 
-A new Flutter project for phone login.
+A Flutter application for phone number-based authentication with Firebase. This app demonstrates a complete phone login flow including phone number input, SMS verification, and authenticated user interfaces.
+
+## Features
+
+- Phone number authentication using Firebase
+- International phone number input with country selection
+- SMS verification with 6-digit code input
+- Responsive UI with adaptive light/dark themes
+- Proper state management with error handling
+- Clean architecture following Flutter best practices
+- Proper separation of concerns (presentation, domain, data layers)
+
+## Architecture
+
+The application follows a layered architecture with the following key components:
+
+- **Authentication**: Managed through Firebase Authentication with `firebase_auth` package. The `AuthState` class handles authentication state using Provider pattern.
+- **Navigation**: Implemented with `go_router` for declarative routing with authentication-aware redirects.
+- **State Management**: Uses `provider` package with `ChangeNotifierProvider` for global state management.
+- **UI Components**: Built with Flutter's Material Design widgets and enhanced with specialized packages:
+  - `intl_phone_field` for international phone number input
+  - `pinput` for PIN input fields on SMS verification
+
+## Project Structure
+
+```
+lib/
+├── main.dart              # App entry point
+├── app.dart               # MaterialApp setup, theme, and routing
+├── auth/                  # Authentication-related screens and logic
+│   ├── auth_state.dart    # Manages authentication state
+│   ├── phone_input_screen.dart
+│   └── sms_verification_screen.dart
+├── home/                  # Home screen
+│   └── home_screen.dart
+├── profile/               # User profile screen
+│   └── profile_screen.dart
+├── services/              # Backend services (e.g., Firebase)
+│   └── auth_service.dart
+├── shared/                # Common models, widgets, and utilities
+│   ├── models/
+│   │   └── user_model.dart
+│   └── widgets/
+│       └── loading_indicator.dart
+└── theme/                 # Theming and styling
+    └── app_theme.dart
+```
 
 ## Getting Started
 
-This project is a starting point for a Flutter application.
+This project is a starting point for a Flutter application with phone authentication capabilities.
 
-A few resources to get you started if this is your first Flutter project:
+### Prerequisites
 
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
+- Flutter SDK (latest stable)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+- Firebase project configured with phone authentication enabled
 
-For help getting started with Flutter development, view the
+### Installation
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
+
-samples, guidance on mobile development, and a full API reference.
+1. Clone the repository
+2. Run `flutter pub get` to install dependencies
+3. Configure Firebase for your platform (Android/iOS)
+4. Run the application with `flutter run`
+
+### Running the Application
+
+```bash
+# Run the application
+flutter run
+
+# Run tests
+flutter test
+
+# Analyze code
+flutter analyze
+
+# Format code
+dart format lib/
+
+# Build for Android
+flutter build apk
+
+# Build for iOS
+flutter build ios
+```
+
+## Key Dependencies
+
+- `firebase_core`: 4.3.0
+- `firebase_auth`: 6.1.3
+- `go_router`: ^17.0.1
+- `provider`: ^6.1.5+1
+- `intl_phone_field`: ^3.2.0
+- `pinput`: ^6.0.1
+
+## Development Best Practices
+
+This project follows Flutter and Dart best practices including:
+
+- Proper separation of concerns
+- Clean architecture with distinct layers
+- State management with proper error handling
+- Responsive UI design
+- Comprehensive error handling and loading states
+- Proper resource disposal
+- Null safety compliance
+- Code formatting and linting