هيكل المشروع والتنظيم Project Structure & Organization

تطبيق MRE CashBook مش بس كود Dart، ده بيحتوي على ملفات لإعدادات منصات كتير زي أندرويد و iOS و Shorebird.

MRE CashBook isn't just Dart code; it contains configuration files for many platforms like Android, iOS, and Shorebird.

ls -F

بنستخدم في المشروع ده Clean Architecture مقرونة بـ Modular Structure. يعني الكود متقسم لجزئين كبار:

We use Clean Architecture combined with Modular Structure in this project. The code is split into two major parts:

مجلد lib/core/ هو المخ اللي بيحرك الدنيا. تعالو نشوف تقسيمته من جوه:

The lib/core/ folder is the brain that runs everything. Let's look at its internal structure:

class AppConfig {
  static const String appName = 'MRE CashBook';
  static const String devEmail = 'dev@mrecode.net';
}

extension BuildContextHelper on BuildContext {
  AppColors get colors => Theme.of(this).extension()!;
  TextTheme get textTheme => Theme.of(this).textTheme;
}

ممنوع نستخدم Raw Material Widgets في الـ Screens. كل حاجة لازم تمر من خلال الـ Core Widgets عشان نضمن شكل موحد.

Raw Material Widgets are forbidden in Screens. Everything must go through Core Widgets to ensure a consistent look.

class AppTextField extends StatelessWidget {
  // تغليف للـ TextFormField بتصميم المشروع
  @override
  Widget build(BuildContext context) {
    return TextFormField(
      decoration: InputDecoration(
        borderRadius: AppSizes.radiusSm,
        fillColor: context.colors.surface,
        // ... إعدادات تانية كتير
      ),
    );
  }
}

ls lib/core/widgets

كل ميزة في MRE CashBook هي تطبيق صغير لوحده. تعالو نشوف ميزة "الكتب" (Books) كمثال:

Every feature in MRE CashBook is a mini-app. Let's look at the "Books" feature as an example:

books/data/
├── models/         # BookDTO, BookMapper
└── datasources/    # local_data_source.dart (Drift)

books/domain/
├── entities/       # Pure Book class
└── repositories/   # Abstract interface

books/presentation/
├── bloc/           # state, event, bloc files
├── screens/        # books_screen.dart
└── widgets/        # book_card.dart, delete_dialog.dart

عشان نحافظ على نضافة الكود، حطينا قواعد ممنوع كسرها:

• ممنوع ميزة تستورد ملفات من ميزة تانية (Cross-Feature Import).
• ممنوع الـ Screen يكلم الـ Database مباشرة.
• ممنوع الـ Business Logic يكون موجود في الـ UI.
• دائماً افصل الـ BLoC في 3 ملفات (State, Event, Bloc).

مجلد assets/ هو مخزن المواد الخام للتصميم.

assets/
├── icon/           # App icons (icon.png)
├── images/         # Splash and backgrounds
├── fonts/          # Custom typography (Inter, Cairo)
└── translations/   # en.dart, ar.dart (Easy Localization)

وعشان نستخدم الـ Assets دي، لازم نسجلها في pubspec.yaml:

flutter:
  uses-material-design: true
  assets:
    - assets/icon/
    - assets/images/
    - assets/translations/
  fonts:
    - family: Inter
      fonts:
        - asset: assets/fonts/Inter-Regular.ttf

حقن التبعيات هو اللي بيربط الطبقات ببعض. في MRE CashBook، كل ميزة عندها ملف `_injection.dart` خاص بيها عشان منعملش زحمة في الملف الرئيسي.

Dependency Injection (DI) is what glues the layers together. In MRE CashBook, every feature has its own `_injection.dart` file to avoid cluttering the main entry point.

final dashboardInjection = DashboardInjection();

class DashboardInjection {
  void init() {
    // تسجيل المستودعات (Repositories)
    sl.registerLazySingleton(
      () => DashboardRepositoryImpl(sl()),
    );
    // تسجيل الـ BLoCs
    sl.registerFactory(() => DashboardBloc(sl()));
  }
}

رغم إن Flutter هو تطبيق Cross-Platform، بس أحياناً بنحتاج نظبط حاجات في الكود الأصلي (Native).

Even though Flutter is cross-platform, sometimes we need to tweak the native code.

cat android/app/src/main/AndroidManifest.xml

جذر المشروع مليان ملفات .yaml و .json. كل واحد ليه وظيفة مهمة جداً.

fvm flutter --version

مجلد test/ مش للديكور، ده الضمان إننا متبوظش حاجة وإحنا بنطور.

test/
├── core/           # Testing shared utils
└── features/       # Feature-specific unit tests
    └── books/
        └── books_bloc_test.dart

لو طلبنا منك تضيف ميزة "التقارير" (Reports)، دي الخطوات اللي لازم تمشي عليها بالظبط عشان تحافظ على الهيكل:

If we asked you to add a "Reports" feature, these are the exact steps you must follow to maintain the structure:

mkdir -p lib/features/reports/{data,domain,presentation}/{models,datasources,entities,repositories,bloc,screens,widgets}

class Report {
  final String id;
  final DateTime date;
  // ...
}

تطبيق MRE مصمم يشتغل على الموبايل والتابلت والـ iPad Pro. عشان كده بنستخدم تقسيم خاص في الـ widgets:

MRE is designed for mobile, tablet, and iPad Pro. That's why we use a specific split in widgets:

عشان المشروع يفضل "Clean"، إحنا مش بنعتمد بس على شطارة المبرمج، إحنا بنستخدم Linter قوي بيراقب كل سطر بيتكتب في الـ analysis_options.yaml.

To keep the project clean, we don't just rely on dev skill; we use a powerful Linter that monitors every line in analysis_options.yaml.

dart analyze

الـ sl (Service Locator) هو اللي بيشيل كل المفاتيح بتاعة التطبيق. بيتم تشغيله في ملف lib/core/di/injection_container.dart.

final sl = GetIt.instance; // المحرك الأساسي (GetIt)

Future init() async {
  // 1. الأساسيات (Core)
  sl.registerLazySingleton(() => AppConfig());
  
  // 2. الميزات (Features)
  dashboardInjection.init();
  booksInjection.init();
  settingsInjection.init();
}

ازاي الطلب بيمشي جوه المشروع؟ من الشاشة لحد قاعدة البيانات والرجوع تاني:

[UI Screen] 
    |--> [BLoC/Cubit] (Presentation)
           |--> [Repository Interface] (Domain)
                  |--> [Repository Implementation] (Data)
                         |--> [Local DataSource] (Data/Drift)
                                |--> [SQLite DB]
      

الرجوع (Response) بيمشي العكس تماماً، بس بشهادة "Entity" مش "Model".

اختبر نفسك! حاول تلاقي مسار الملفات دي من غير ما تبص على الشرح تاني:

الملف ده هو المسؤول عن استيراد كل العضلات اللي التطبيق بيستخدمها. تعالو نشوف أهم المكاتب (Dependencies) اللي فيه:

fvm flutter pub get

لو وصلت لحد هنا، فأنت دلوقتي مبرمج فاهم كل "سنتيمتر" في هيكل مشروع MRE CashBook. أنت جاهز تدخل في عمق الكود وتغير أي حاجة وأنت مطمن.

If you reached this far, you now understand every "centimeter" of the MRE CashBook structure. You are ready to dive deep into the code and change anything with confidence.

هل كنت تعرف إن الطريقة اللي بننظم بيها الفولدرات بتأثر على سرعة التطبيق؟

Did you know that how we organize folders affects app speed?

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

It's been a long journey through files and folders. Don't look at this structure as a restriction, but as a treasure map guiding you to stable, testable, and easy-to-develop code. In the next chapter, we'll start dealing with real data in the "Database".

دلوقتي بقيت عارف إزاي MRE CashBook بيحافظ على نظافة وترتيب ملفاته. الفصل ده هو حجر الأساس لفهم باقي الفصول.

Now you know how MRE CashBook maintains its file cleanliness and order. This chapter is the foundation for understanding the rest of the course.