هو تطبيق أندرويد و iOS لإدارة السجلات المالية الشخصية (Ledger) والمعاملات اليومية. يركز التطبيق على الخصوصية (Private) والعمل بدون إنترنت (Offline-first) مع توفير أدوات احترافية مثل تصدير التقارير بصيغة PDF والنسخ الاحتياطي المشفر.

It's an Android & iOS application for managing personal financial ledgers and daily transactions. The app focuses on privacy and an offline-first experience, providing professional tools like PDF report export and encrypted backups.

قبل ما نفتح الكود، لازم نتأكد إن كل المكتبات جاهزة. بنستخدم أمر `flutter pub get` الأساسي.

Before we open the code, we must ensure all libraries are ready. We use the fundamental `flutter pub get` command.

flutter pub get

التطبيق بيعتمد على مجموعة من المكتبات القوية. في ملف `pubspec.yaml` بنلاحظ استخدام علامة الـ `^` (Caret) قبل أرقام النسخ.

The app relies on a set of powerful libraries. In `pubspec.yaml`, we notice the use of the `^` (Caret) symbol before version numbers.

بنستخدم Clean Architecture مقسمة لثلاث طبقات أساسية. ده بيضمن إننا لو حبينا نغير قاعدة البيانات مستقبلاً، مش هنحتاج نغير حاجة في الـ UI.

We use Clean Architecture divided into three main layers. This ensures that if we want to change the database in the future, we won't need to change anything in the UI.

يبدأ التطبيق في `main.dart` حيث يتم تجهيز كل شيء قبل ظهور أول شاشة للمستخدم. يتم تهيئة الـ Dependency Injection، الـ Database، وخدمات Firebase.

The app starts in `main.dart` where everything is prepared before the first screen appears. DI, Database, and Firebase services are initialized here.

void main() async {
  try {
    // Ensuring Flutter is ready for async calls
    WidgetsFlutterBinding.ensureInitialized();

    // 1. Initialize Dependency Injection (GetIt)
    await initDI();

    try {
      // 2. Initialize Firebase with a 3-second timeout
      await Firebase.initializeApp(
        options: DefaultFirebaseOptions.currentPlatform,
      ).timeout(
        const Duration(seconds: 3),
        onTimeout: () => throw Exception('Firebase init timeout'),
      );
      
      // Setup Crashlytics
      FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterError;
    } catch (e) {
      debugPrint('Firebase failed: $e');
    }

    // 3. Global Bloc Observer for debugging
    Bloc.observer = AppBlocObserver();

    // 4. Run the Application
    runApp(const LedgerApp());
    
  } catch (e) {
    debugPrint('Critical Failure: $e');
  }
}

Main() ──► initDI() ──► Firebase Init ──► Error Handlers ──► runApp(LedgerApp)
                                         │
                                         └─► MultiBlocProvider
                                              ├─ AppSettingsCubit
                                              ├─ AppPreferencesCubit
                                              └─ BooksBloc
      

التطبيق محتاج يوصل للصور والخطوط. ده بيتم تعريفه في قسم `flutter:` داخل `pubspec.yaml`.

The app needs access to images and fonts. This is defined in the `flutter:` section of `pubspec.yaml`.

flutter:
  uses-material-design: true

  assets:
    - assets/images/
    - assets/icons/
    - assets/splash/
    - assets/lottie/

في `main.dart` بنستخدم `protected` blocks عشان نضمن إن أي مشكلة في البداية متبوظش تجربة المستخدم.

In `main.dart`, we use protected blocks to ensure startup issues don't ruin the user experience.

// Capture Async errors outside Flutter Context
PlatformDispatcher.instance.onError = (error, stack) {
  FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
  return true;
};

// Custom Error Widget for UI crashes
ErrorWidget.builder = (FlutterErrorDetails details) {
  return Scaffold(
    body: Center(
      child: Text('هناك خطأ ما، تم إبلاغ المطورين.'),
    ),
  );
};

بنستخدم FVM (Flutter Version Management) للتأكد إن كل المطورين شغالين بظبط على نفس نسخة Flutter (وهي 3.24.5 في مشروعنا).

We use FVM (Flutter Version Management) to ensure all developers use the exact same Flutter version (3.24.5 in our project).

fvm flutter run

المشروع ده بيتبع مبادئ الـ "MRE" والـ "Clean Code". الهدف هو إن الكود يكون بيشرح نفسه (Self-documenting).

The project follows "MRE" and "Clean Code" principles. The goal is self-documenting code.

• M (Modular): كل ميزة (Feature) معزولة لوحدها.
• R (Resilient): التطبيق بيقدر يتعامل مع الأخطاء (Errors) من غير ما ينهار.
• E (Efficient): الكود مكتوب بأعلى أداء (Performance) مع استهلاك قليل للموارد.

قواعد ذهبية ممنوع كسرها:

• ممنوع وضع Logic داخل الـ Widgets (UI).
• ممنوع استخدام Magic Numbers (أرقام ثابتة) بدون تعريفها في `AppSizes`.
• كل Bloc لازم يتقسم لـ 3 ملفات منفصلة.

أنهينا نظرة عامة شاملة على المشروع، من أول "ما هو التطبيق" لحد "إزاي نشغله" و "إيه الأدوات اللي بنستخدمها".

We finished a comprehensive project overview, from "What is the app" to "How to run it" and "What tools we use".

• الفصل الثاني: هنشوف الـ Git history الحقيقي للتطوير.
• الفصل الثالث: هنحلل كل فولدر في المشروع.
• الفصل الرابع: الغوص في قاعدة البيانات (Drift).