diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md
new file mode 100644
index 00000000..00ee9672
--- /dev/null
+++ b/PROJECT_ARCHITECTURE.md
@@ -0,0 +1,1768 @@
+
+You are a senior Flutter developer. You will be given this entire document as your specification.
+Your task: generate a complete, compilable Flutter project from scratch following every instruction below.
+Do NOT skip any file. Do NOT summarize. Generate FULL, working Dart code for every file listed.
+When you see placeholder names like `{{APP_NAME}}`, `{{PACKAGE_NAME}}`, `{{BASE_URL}}`, replace them with the values the user provides. If no values are provided, use the defaults in Section 1.
+
+
+# Flutter Project Generator — Architecture Specification
+
+> **What this document is:** A precise, machine-readable specification for an AI to generate a greenfield Flutter project. Every file path, every class, every method signature, and every pattern is defined below with copy-ready code. Follow it top-to-bottom.
+
+---
+
+## 1. DEFAULTS — Replace These for Your Project
+
+```
+APP_NAME = "My App"
+DART_PACKAGE = "my_app"
+ORG_IDENTIFIER = "com.example.myapp"
+BASE_URL = "https://api.example.com/"
+PRIMARY_COLOR = 0xFFED1C2B (Red)
+FIGMA_WIDTH = 430
+FIGMA_HEIGHT = 927
+SUPPORTED_LOCALES = [en-US, ar-SA]
+PRIMARY_FONT = "Poppins"
+SECONDARY_FONT = "GESSTwo" (Arabic font)
+```
+
+When the user asks you to generate this project, first ask them for these values. If they say "use defaults," use the values above.
+
+---
+
+## 2. COMMAND — Create the Flutter Project
+
+Run this first:
+```bash
+flutter create --org {{ORG_IDENTIFIER}} --project-name {{DART_PACKAGE}} {{DART_PACKAGE}}
+cd {{DART_PACKAGE}}
+```
+
+---
+
+## 3. FILE: `pubspec.yaml`
+
+Generate this file EXACTLY. Do not add or remove packages.
+
+```yaml
+name: {{DART_PACKAGE}}
+description: "{{APP_NAME}}"
+publish_to: 'none'
+version: 1.0.0+1
+
+environment:
+ sdk: ">=3.6.0 <4.0.0"
+
+dependencies:
+ flutter:
+ sdk: flutter
+ flutter_localizations:
+ sdk: flutter
+
+ # === Core Architecture ===
+ provider: ^6.1.5+1
+ get_it: ^8.2.0
+ dartz: ^0.10.1
+ equatable: ^2.0.7
+
+ # === Networking ===
+ http: ^1.5.0
+ connectivity_plus: ^6.1.5
+
+ # === Firebase ===
+ firebase_core: any
+ firebase_messaging: ^15.2.10
+ firebase_analytics: ^11.5.1
+ firebase_crashlytics: ^4.3.8
+
+ # === UI ===
+ cupertino_icons: ^1.0.8
+ flutter_svg: ^2.2.0
+ cached_network_image: ^3.4.1
+ auto_size_text: ^3.0.0
+ shimmer: ^3.0.0
+ sizer: ^3.1.3
+ lottie: ^3.3.1
+ smooth_corner: ^1.1.1
+ flutter_staggered_animations: ^1.1.1
+ fl_chart: 1.0.0
+ flutter_rating_bar: ^4.0.1
+
+ # === Localization ===
+ easy_localization: ^3.0.8
+ intl: ^0.20.2
+
+ # === Storage ===
+ shared_preferences: ^2.5.3
+ path_provider: ^2.0.8
+
+ # === Device ===
+ permission_handler: ^12.0.1
+ local_auth: ^2.3.0
+ device_info_plus: ^11.5.0
+ image_picker: ^1.2.0
+ url_launcher: ^6.3.2
+ share_plus: ^11.1.0
+
+ # === Notifications ===
+ flutter_local_notifications: ^19.4.1
+ timezone: ^0.10.0
+ fluttertoast: ^8.2.12
+
+ # === Logging ===
+ logger: ^2.6.1
+
+dev_dependencies:
+ flutter_test:
+ sdk: flutter
+ flutter_lints: ^5.0.0
+
+flutter:
+ uses-material-design: true
+ assets:
+ - assets/
+ - assets/json/
+ - assets/fonts/
+ - assets/langs/
+ - assets/images/
+ - assets/images/svg/
+ - assets/images/png/
+ - assets/animations/
+ - assets/animations/lottie/
+
+ fonts:
+ - family: Poppins
+ fonts:
+ - asset: assets/fonts/poppins/Poppins-SemiBold.ttf
+ weight: 600
+ - asset: assets/fonts/poppins/Poppins-Medium.ttf
+ weight: 500
+ - asset: assets/fonts/poppins/Poppins-Regular.ttf
+ weight: 400
+ - asset: assets/fonts/poppins/Poppins-Light.ttf
+ weight: 300
+```
+
+> **Note:** If the user provides a SECONDARY_FONT, add its font family block here too.
+
+---
+
+## 4. FILE: `analysis_options.yaml`
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+
+linter:
+ rules:
+ # prefer_single_quotes: true
+```
+
+---
+
+## 5. FOLDER STRUCTURE — Create ALL These Directories
+
+```bash
+mkdir -p lib/core/api
+mkdir -p lib/core/common_models
+mkdir -p lib/core/exceptions
+mkdir -p lib/core/utils
+mkdir -p lib/services/analytics
+mkdir -p lib/features
+mkdir -p lib/presentation/home/widgets
+mkdir -p lib/presentation/authentication
+mkdir -p lib/presentation/onboarding
+mkdir -p lib/routes
+mkdir -p lib/theme
+mkdir -p lib/extensions
+mkdir -p lib/widgets/buttons
+mkdir -p lib/widgets/loader
+mkdir -p lib/widgets/bottomsheet
+mkdir -p lib/widgets/bottom_navigation
+mkdir -p lib/widgets/shimmer
+mkdir -p lib/widgets/routes
+mkdir -p lib/generated
+mkdir -p assets/fonts/poppins
+mkdir -p assets/images/svg
+mkdir -p assets/images/png
+mkdir -p assets/animations/lottie
+mkdir -p assets/json
+mkdir -p assets/langs
+mkdir -p assets/sounds
+```
+
+---
+
+## 6. CORE LAYER — Generate Each File Exactly
+
+### 6.1 FILE: `lib/core/enums.dart`
+
+```dart
+enum ViewStateEnum { hide, idle, busy, error, busyLocal, errorLocal }
+
+enum AppEnvironmentTypeEnum { dev, uat, preProd, qa, staging, prod }
+
+enum GenderTypeEnum { male, female }
+
+enum ChipTypeEnum { success, error, alert, info, warning, lightBg, primaryRed }
+
+enum LoginTypeEnum { sms, whatsapp, face, fingerprint }
+
+enum OTPTypeEnum { sms, whatsapp, faceIDFingerprint }
+```
+
+### 6.2 FILE: `lib/core/exceptions/api_failure.dart`
+
+```dart
+import 'package:equatable/equatable.dart';
+
+abstract class Failure extends Equatable implements Exception {
+ final String message;
+ const Failure(this.message);
+}
+
+class ServerFailure extends Failure {
+ final String url;
+ const ServerFailure(super.message, {this.url = ""});
+ @override
+ List