# Flutter Project Structure - AI Study Assistant

## 📁 COMPLETE PROJECT ARCHITECTURE

---

## 🏗️ OVERVIEW

This document outlines the complete Flutter project structure for the AI Study Assistant, following clean architecture principles and best practices for scalable, maintainable code.

---

## 📁 ROOT DIRECTORY STRUCTURE

```
teachit/
├── android/                     # Android-specific files
├── ios/                         # iOS-specific files
├── web/                         # Web-specific files
├── lib/                         # Main Flutter source code
├── test/                        # Test files
├── assets/                      # Static assets
├── docs/                        # Documentation
├── tools/                       # Development tools and scripts
├── .gitignore                   # Git ignore file
├── .metadata                    # Flutter metadata
├── pubspec.yaml                 # Dependencies and project config
├── README.md                    # Project documentation
├── analysis_options.yaml        # Dart analysis configuration
└── .vscode/                     # VS Code configuration
    ├── launch.json               # Debug configurations
    ├── tasks.json               # Build tasks
    └── settings.json             # Editor settings
```

---

## 📚 LIB DIRECTORY STRUCTURE

### Main Source Code Organization

```
lib/
├── main.dart                    # Application entry point
├── app/                         # App-level configuration
│   ├── app.dart                 # Main app widget
│   ├── router/                  # Navigation configuration
│   │   ├── app_router.dart      # GoRouter configuration
│   │   ├── routes.dart          # Route definitions
│   │   └── route_guard.dart     # Route guards/middleware
│   ├── theme/                   # Theme and styling
│   │   ├── app_theme.dart       # Main theme configuration
│   │   ├── app_colors.dart      # Color palette
│   │   ├── app_text_styles.dart # Typography
│   │   ├── app_spacing.dart     # Spacing constants
│   │   └── dark_theme.dart      # Dark mode theme
│   ├── constants/               # App-wide constants
│   │   ├── app_constants.dart   # General app constants
│   │   ├── api_constants.dart   # API endpoints
│   │   ├── firebase_constants.dart # Firebase references
│   │   └── route_constants.dart # Route paths
│   └── widgets/                 # App-level reusable widgets
│       ├── app_scaffold.dart    # Main scaffold wrapper
│       ├── app_bottom_navigation.dart # Bottom navigation
│       ├── app_drawer.dart      # Navigation drawer
│       ├── app_sliver_app_bar.dart # Custom app bar
│       └── loading_overlay.dart  # Global loading overlay
├── core/                        # Core functionality (cross-features)
│   ├── errors/                  # Error handling
│   │   ├── exceptions.dart      # Custom exceptions
│   │   ├── failures.dart        # Failure classes
│   │   └── error_handler.dart   # Global error handler
│   ├── utils/                   # Utility functions
│   │   ├── logger.dart          # Logging utility
│   │   ├── validators.dart      # Input validators
│   │   ├── extensions.dart      # Dart extensions
│   │   ├── helpers.dart         # Helper functions
│   │   ├── date_utils.dart      # Date utilities
│   │   └── formatters.dart      # Data formatters
│   ├── services/                # Global services
│   │   ├── storage_service.dart # Local storage
│   │   ├── notification_service.dart # Notifications
│   │   ├── network_service.dart # Network connectivity
│   │   ├── biometric_service.dart # Biometric auth
│   │   └── analytics_service.dart # Analytics tracking
│   ├── network/                 # Network layer
│   │   ├── dio_client.dart      # HTTP client configuration
│   │   ├── interceptors.dart    # Request/response interceptors
│   │   ├── api_client.dart      # API client wrapper
│   │   └── network_info.dart    # Network connectivity
│   └── security/                # Security features
│       ├── encryption.dart      # Encryption utilities
│       ├── secure_storage.dart  # Secure storage
│       └── auth_manager.dart    # Authentication manager
├── features/                    # Feature-based organization
│   ├── auth/                    # Authentication feature
│   │   ├── data/                # Data layer
│   │   │   ├── datasources/     # Data sources
│   │   │   │   ├── auth_remote_datasource.dart # Remote API
│   │   │   │   ├── auth_local_datasource.dart  # Local storage
│   │   │   │   └── auth_cache_datasource.dart   # Cache layer
│   │   │   ├── models/          # Data models
│   │   │   │   ├── user_model.dart
│   │   │   │   ├── auth_result_model.dart
│   │   │   │   ├── token_model.dart
│   │   │   │   └── role_model.dart
│   │   │   └── repositories/    # Repository implementations
│   │   │       └── auth_repository_impl.dart
│   │   ├── domain/              # Business logic
│   │   │   ├── entities/        # Domain entities
│   │   │   │   ├── user.dart
│   │   │   │   ├── auth_result.dart
│   │   │   │   ├── token.dart
│   │   │   │   └── role.dart
│   │   │   ├── repositories/    # Repository interfaces
│   │   │   │   └── auth_repository.dart
│   │   │   └── usecases/        # Use cases (business logic)
│   │   │       ├── sign_in.dart
│   │   │       ├── sign_up.dart
│   │   │       ├── sign_out.dart
│   │   │       ├── reset_password.dart
│   │   │       ├── get_current_user.dart
│   │   │       ├── update_profile.dart
│   │   │       └── refresh_token.dart
│   │   └── presentation/       # UI layer
│   │       ├── providers/       # State management (Riverpod)
│   │       │   ├── auth_provider.dart
│   │       │   ├── user_provider.dart
│   │       │   ├── session_provider.dart
│   │       │   └── auth_state_provider.dart
│   │       ├── screens/         # Screen widgets
│   │       │   ├── login_screen.dart
│   │       │   ├── signup_screen.dart
│   │       │   ├── forgot_password_screen.dart
│   │       │   ├── profile_setup_screen.dart
│   │       │   └── email_verification_screen.dart
│   │       └── widgets/         # Feature-specific widgets
│   │           ├── auth_form.dart
│   │           ├── social_login_button.dart
│   │           ├── password_input_field.dart
│   │           ├── email_input_field.dart
│   │           ├── terms_checkbox.dart
│   │           └── verification_code_input.dart
│   ├── student/                 # Student feature
│   │   ├── data/
│   │   │   ├── datasources/
│   │   │   │   ├── student_remote_datasource.dart
│   │   │   │   ├── student_local_datasource.dart
│   │   │   │   └── learning_state_datasource.dart
│   │   │   ├── models/
│   │   │   │   ├── student_model.dart
│   │   │   │   ├── learning_state_model.dart
│   │   │   │   ├── concept_mastery_model.dart
│   │   │   │   ├── quiz_attempt_model.dart
│   │   │   │   ├── interaction_model.dart
│   │   │   │   ├── feedback_model.dart
│   │   │   │   └── recommendation_model.dart
│   │   │   └── repositories/
│   │   │       ├── student_repository_impl.dart
│   │   │       ├── learning_state_repository_impl.dart
│   │   │       └── quiz_repository_impl.dart
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── student.dart
│   │   │   │   ├── learning_state.dart
│   │   │   │   ├── concept_mastery.dart
│   │   │   │   ├── quiz_attempt.dart
│   │   │   │   ├── interaction.dart
│   │   │   │   ├── feedback.dart
│   │   │   │   ├── recommendation.dart
│   │   │   │   ├── learning_goal.dart
│   │   │   │   └── spaced_repetition.dart
│   │   │   ├── repositories/
│   │   │   │   ├── student_repository.dart
│   │   │   │   ├── learning_state_repository.dart
│   │   │   │   └── quiz_repository.dart
│   │   │   └── usecases/
│   │   │       ├── get_learning_state.dart
│   │   │       ├── update_learning_state.dart
│   │   │       ├── submit_quiz_attempt.dart
│   │   │       ├── get_quiz_history.dart
│   │   │       ├── get_recommendations.dart
│   │   │       ├── submit_feedback.dart
│   │   │       ├── track_interaction.dart
│   │   │       ├── update_mastery.dart
│   │   │       └── get_progress_analytics.dart
│   │   └── presentation/
│   │       ├── providers/
│   │       │   ├── student_provider.dart
│   │       │   ├── learning_state_provider.dart
│   │       │   ├── quiz_provider.dart
│   │       │   ├── chat_provider.dart
│   │       │   ├── recommendation_provider.dart
│   │       │   └── progress_provider.dart
│   │       ├── screens/
│   │       │   ├── student_dashboard_screen.dart
│   │       │   ├── ask_tutor_screen.dart
│   │       │   ├── quiz_screen.dart
│   │       │   ├── progress_screen.dart
│   │       │   ├── profile_screen.dart
│   │       │   ├── recommendations_screen.dart
│   │       │   ├── quiz_history_screen.dart
│   │       │   └── settings_screen.dart
│   │       └── widgets/
│   │           ├── mastery_progress_bar.dart
│   │           ├── concept_card.dart
│   │           ├── quiz_question_card.dart
│   │           ├── chat_bubble.dart
│   │           ├── feedback_widget.dart
│   │           ├── recommendation_card.dart
│   │           ├── learning_streak_widget.dart
│   │           ├── misconception_alert.dart
│   │           └── progress_chart.dart
│   ├── teacher/                 # Teacher feature
│   │   ├── data/
│   │   │   ├── datasources/
│   │   │   │   ├── teacher_remote_datasource.dart
│   │   │   │   ├── teacher_local_datasource.dart
│   │   │   │   ├── content_datasource.dart
│   │   │   │   └── analytics_datasource.dart
│   │   │   ├── models/
│   │   │   │   ├── teacher_model.dart
│   │   │   │   ├── content_model.dart
│   │   │   │   ├── quiz_model.dart
│   │   │   │   ├── class_analytics_model.dart
│   │   │   │   ├── student_summary_model.dart
│   │   │   │   └── content_upload_model.dart
│   │   │   └── repositories/
│   │   │       ├── teacher_repository_impl.dart
│   │   │       ├── content_repository_impl.dart
│   │   │       └── analytics_repository_impl.dart
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── teacher.dart
│   │   │   │   ├── content.dart
│   │   │   │   ├── quiz.dart
│   │   │   │   ├── class_analytics.dart
│   │   │   │   ├── student_summary.dart
│   │   │   │   └── content_upload.dart
│   │   │   ├── repositories/
│   │   │   │   ├── teacher_repository.dart
│   │   │   │   ├── content_repository.dart
│   │   │   │   └── analytics_repository.dart
│   │   │   └── usecases/
│   │   │       ├── upload_content.dart
│   │   │       ├── create_quiz.dart
│   │   │       ├── get_class_analytics.dart
│   │   │       ├── manage_students.dart
│   │   │       ├── get_content_list.dart
│   │   │       ├── update_content.dart
│   │   │       ├── get_student_progress.dart
│   │   │       └── export_analytics.dart
│   │   └── presentation/
│   │       ├── providers/
│   │       │   ├── teacher_provider.dart
│   │       │   ├── content_provider.dart
│   │       │   ├── analytics_provider.dart
│   │       │   ├── class_management_provider.dart
│   │       │   └── quiz_creation_provider.dart
│   │       ├── screens/
│   │       │   ├── teacher_dashboard_screen.dart
│   │       │   ├── upload_content_screen.dart
│   │       │   ├── create_quiz_screen.dart
│   │       │   ├── class_analytics_screen.dart
│   │       │   ├── manage_students_screen.dart
│   │       │   ├── content_library_screen.dart
│   │       │   └── quiz_management_screen.dart
│   │       └── widgets/
│   │           ├── content_upload_card.dart
│   │           ├── quiz_builder.dart
│   │           ├── analytics_chart.dart
│   │           ├── student_list_item.dart
│   │           ├── content_preview.dart
│   │           ├── class_summary_card.dart
│   │           └── export_button.dart
│   ├── shared/                   # Shared components across features
│   │   ├── data/
│   │   │   ├── models/
│   │   │   │   ├── message_model.dart
│   │   │   │   ├── feedback_model.dart
│   │   │   │   ├── notification_model.dart
│   │   │   │   ├── file_model.dart
│   │   │   │   └── app_settings_model.dart
│   │   │   ├── datasources/
│   │   │   │   ├── shared_remote_datasource.dart
│   │   │   │   ├── shared_local_datasource.dart
│   │   │   │   └── file_storage_datasource.dart
│   │   │   └── repositories/
│   │   │       └── shared_repository_impl.dart
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── message.dart
│   │   │   │   ├── feedback.dart
│   │   │   │   ├── notification.dart
│   │   │   │   ├── file.dart
│   │   │   │   └── app_settings.dart
│   │   │   ├── repositories/
│   │   │   │   └── shared_repository.dart
│   │   │   └── usecases/
│   │   │       ├── send_message.dart
│   │   │       ├── submit_feedback.dart
│   │   │       ├── upload_file.dart
│   │   │       ├── get_notifications.dart
│   │   │       └── update_settings.dart
│   │   └── presentation/
│   │       ├── widgets/           # Reusable UI components
│   │       │   ├── buttons/      # Button components
│   │       │   │   ├── primary_button.dart
│   │       │   │   ├── secondary_button.dart
│   │       │   │   ├── icon_button.dart
│   │       │   │   ├── text_button.dart
│   │       │   │   └── floating_action_button.dart
│   │       │   ├── inputs/       # Input components
│   │       │   │   ├── custom_text_field.dart
│   │       │   │   ├── search_field.dart
│   │       │   │   ├── password_field.dart
│   │       │   │   ├── text_area_field.dart
│   │       │   │   └── dropdown_field.dart
│   │       │   ├── cards/        # Card components
│   │       │   │   ├── standard_card.dart
│   │       │   │   ├── interactive_card.dart
│   │       │   │   ├── media_card.dart
│   │       │   │   └── expandable_card.dart
│   │       │   ├── lists/        # List components
│   │       │   │   ├── standard_list_tile.dart
│   │       │   │   ├── expandable_list_tile.dart
│   │       │   │   ├── selection_list_tile.dart
│   │       │   │   └── swipe_list_tile.dart
│   │       │   ├── dialogs/      # Dialog components
│   │       │   │   ├── confirmation_dialog.dart
│   │       │   │   ├── info_dialog.dart
│   │       │   │   ├── input_dialog.dart
│   │       │   │   └── selection_dialog.dart
│   │       │   ├── bottomsheets/ # Bottom sheet components
│   │       │   │   ├── standard_bottom_sheet.dart
│   │       │   │   ├── picker_bottom_sheet.dart
│   │       │   │   └── action_bottom_sheet.dart
│   │       │   ├── indicators/   # Loading and progress
│   │       │   │   ├── loading_widget.dart
│   │       │   │   ├── progress_bar.dart
│   │       │   │   ├── shimmer_loading.dart
│   │       │   │   └── pull_to_refresh.dart
│   │       │   ├── layout/       # Layout components
│   │       │   │   ├── responsive_layout.dart
│   │       │   │   ├── adaptive_layout.dart
│   │       │   │   ├── section_layout.dart
│   │       │   │   └── grid_layout.dart
│   │       │   ├── media/        # Media components
│   │       │   │   ├── image_viewer.dart
│   │       │   │   ├── video_player.dart
│   │       │   │   ├── audio_player.dart
│   │       │   │   └── file_preview.dart
│   │       │   ├── animations/   # Animation components
│   │       │   │   ├── fade_in.dart
│   │       │   │   ├── slide_in.dart
│   │       │   │   ├── scale_in.dart
│   │       │   │   ├── staggered_animation.dart
│   │       │   │   └── page_transition.dart
│   │       │   └── charts/       # Chart components
│   │       │       ├── line_chart.dart
│   │       │       ├── bar_chart.dart
│   │       │       ├── pie_chart.dart
│   │       │       └── progress_chart.dart
│   │       └── providers/       # Shared state providers
│   │           ├── theme_provider.dart
│   │           ├── connectivity_provider.dart
│   │           ├── notification_provider.dart
│   │           ├── settings_provider.dart
│   │           ├── file_provider.dart
│   │           └── biometric_provider.dart
└── l10n/                        # Internationalization
    ├── app_localizations.dart   # Localization setup
    ├── app_en.arb               # English translations
    ├── app_pt.arb               # Portuguese translations
    └── app_es.arb               # Spanish translations
```

---

## 🔧 CONFIGURATION FILES

### pubspec.yaml
```yaml
name: teachit
description: AI Study Assistant - Educational Intelligence Platform
version: 1.0.0+1

environment:
  sdk: '>=3.11.5 <4.0.0'
  flutter: ">=3.41.0"

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter

  # State Management
  flutter_riverpod: ^2.4.9
  riverpod_annotation: ^2.3.3

  # Navigation
  go_router: ^12.1.3
  flutter_animate: ^4.2.0+1

  # Firebase
  firebase_core: ^2.24.2
  firebase_auth: ^4.15.3
  cloud_firestore: ^4.13.6
  firebase_storage: ^11.5.6
  firebase_analytics: ^10.7.4
  firebase_messaging: ^14.7.6
  firebase_crashlytics: ^3.4.8

  # UI Components
  cupertino_icons: ^1.0.6
  google_fonts: ^6.1.0
  cached_network_image: ^3.3.0
  flutter_svg: ^2.0.9
  lottie: ^2.7.0
  shimmer: ^3.0.0
  flutter_staggered_animations: ^1.1.1

  # HTTP & Networking
  dio: ^5.4.0
  http: ^1.1.2
  connectivity_plus: ^5.0.2
  retry: ^3.1.2

  # Local Storage
  shared_preferences: ^2.2.2
  hive: ^2.2.3
  hive_flutter: ^1.1.0
  secure_storage: ^9.0.0
  path_provider: ^2.1.1

  # Utilities
  intl: ^0.19.0
  uuid: ^4.2.1
  equatable: ^2.0.5
  json_annotation: ^4.8.1
  freezed_annotation: ^2.4.1
  collection: ^1.18.0

  # File Handling
  file_picker: ^6.1.1
  image_picker: ^1.0.4
  permission_handler: ^11.0.1
  path: ^1.8.3

  # Charts & Graphs
  fl_chart: ^0.64.0
  syncfusion_flutter_charts: ^24.1.44

  # Biometrics
  local_auth: ^2.1.7

  # WebView
  webview_flutter: ^4.4.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.1
  build_runner: ^2.4.7
  riverpod_generator: ^2.3.9
  json_serializable: ^6.7.1
  freezed: ^2.4.6
  hive_generator: ^2.0.1
  mockito: ^5.4.4
  integration_test:
    sdk: flutter

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/animations/
    - assets/fonts/
  fonts:
    - family: Inter
      fonts:
        - asset: assets/fonts/Inter-Regular.ttf
        - asset: assets/fonts/Inter-Medium.ttf
          weight: 500
        - asset: assets/fonts/Inter-SemiBold.ttf
          weight: 600
        - asset: assets/fonts/Inter-Bold.ttf
          weight: 700
```

### analysis_options.yaml
```yaml
include: package:flutter_lints/flutter.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
  errors:
    invalid_annotation_target: ignore
    unused_import: ignore
    unused_element: ignore

linter:
  rules:
    # Style rules
    - prefer_single_quotes
    - sort_constructors_first
    - sort_unnamed_constructors_first
    - always_declare_return_types
    - avoid_print
    - avoid_unnecessary_containers
    - prefer_const_constructors
    - prefer_const_literals_to_create_immutables
    - prefer_final_fields
    - prefer_final_locals
    - unnecessary_const
    - unnecessary_new
    - prefer_if_elements_to_conditional_expressions
    
    # Documentation rules
    - slash_for_doc_comments
    - package_api_docs
    - comment_references
    
    # Design rules
    - avoid_web_libraries_in_flutter
    - avoid_type_to_string
    - cast_nullable_to_non_nullable
    - deprecated_consistency
    - implicit_call_tearoffs
    - library_prefixes
    - omit_local_variable_types
    - prefer_adjacent_string_concatenation
    - prefer_function_declarations_over_variables
    - prefer_mixin
    - type_annotate_public_apis
    - unnecessary_await_in_return
    - unnecessary_lambdas
    - use_super_parameters
```

---

## 📱 PLATFORM-SPECIFIC FILES

### Android Configuration

**android/app/build.gradle**
```gradle
android {
    namespace 'com.example.teachit'
    compileSdkVersion flutter.compileSdkVersion

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = '17'
    }

    defaultConfig {
        applicationId "com.example.teachit"
        minSdkVersion 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
        multiDexEnabled true
    }

    buildTypes {
        release {
            signingConfig signingConfigs.debug
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
        debug {
            minifyEnabled false
        }
    }
}

dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'com.google.firebase:firebase-messaging'
    implementation 'com.google.firebase:firebase-analytics'
}
```

### iOS Configuration

**ios/Runner/Info.plist**
```xml
<key>CFBundleDisplayName</key>
<string>TeachIt</string>
<key>CFBundleIdentifier</key>
<string>com.example.teachit</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>UISupportedInterfaceOrientations</key>
<array>
    <string>UIInterfaceOrientationPortrait</string>
    <string>UIInterfaceOrientationLandscapeLeft</string>
    <string>UIInterfaceOrientationLandscapeRight</string>
</array>
<key>UIStatusBarStyle</key>
<string>UIStatusBarStyleLightContent</string>
<key>NSCameraUsageDescription</key>
<string>This app needs camera access for profile photos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access for profile photos</string>
```

---

## 🧪 TEST STRUCTURE

### Test Organization
```
test/
├── unit/                       # Unit tests
│   ├── features/
│   │   ├── auth/
│   │   │   ├── test_auth_provider.dart
│   │   │   ├── test_sign_in_usecase.dart
│   │   │   └── test_user_model.dart
│   │   ├── student/
│   │   │   ├── test_learning_state_provider.dart
│   │   │   ├── test_quiz_provider.dart
│   │   │   └── test_concept_mastery.dart
│   │   └── shared/
│   │       ├── test_widgets.dart
│   │       └── test_utils.dart
│   ├── core/
│   │   ├── test_services.dart
│   │   ├── test_utils.dart
│   │   └── test_network.dart
│   └── helpers/
│       ├── test_helpers.dart
│       ├── mock_data.dart
│       └── test_fixtures.dart
├── widget/                     # Widget tests
│   ├── features/
│   │   ├── auth/
│   │   │   ├── test_login_screen.dart
│   │   │   └── test_signup_screen.dart
│   │   ├── student/
│   │   │   ├── test_dashboard_screen.dart
│   │   │   └── test_chat_screen.dart
│   │   └── shared/
│   │       ├── test_buttons.dart
│   │       ├── test_cards.dart
│   │       └── test_inputs.dart
│   └── helpers/
│       ├── widget_test_helpers.dart
│       └── mock_providers.dart
├── integration/                # Integration tests
│   ├── test_auth_flow.dart
│   ├── test_student_dashboard.dart
│   ├── test_teacher_dashboard.dart
│   └── test_chat_functionality.dart
└── e2e/                       # End-to-end tests
    ├── app_test.dart
    ├── auth_flow_test.dart
    └── learning_flow_test.dart
```

---

## 📦 ASSETS ORGANIZATION

### Asset Structure
```
assets/
├── images/
│   ├── logos/
│   │   ├── app_logo.png
│   │   ├── app_logo_dark.png
│   │   └── epvc_logo.png
│   ├── icons/
│   │   ├── app_icon.png
│   │   ├── notification_icon.png
│   │   └── placeholder.png
│   ├── illustrations/
│   │   ├── learning_illustration.svg
│   │   ├── studying_illustration.svg
│   │   └── success_illustration.svg
│   └── backgrounds/
│       ├── login_bg.png
│       ├── dashboard_bg.png
│       └── onboarding_bg.png
├── animations/
│   ├── loading_animation.json
│   ├── success_animation.json
│   ├── error_animation.json
│   └── onboarding_animation.json
├── fonts/
│   ├── Inter-Regular.ttf
│   ├── Inter-Medium.ttf
│   ├── Inter-SemiBold.ttf
│   ├── Inter-Bold.ttf
│   └── Inter-Italic.ttf
└── data/
    ├── sample_quiz_data.json
    ├── mock_user_data.json
    └── test_content.json
```

---

## 🔧 DEVELOPMENT TOOLS

### Tool Scripts
```
tools/
├── scripts/
│   ├── build_runner.sh         # Run code generation
│   ├── test_runner.sh          # Run all tests
│   ├── format_code.sh          # Format Dart code
│   ├── analyze_code.sh         # Static analysis
│   ├── generate_icons.sh       # Generate app icons
│   └── deploy_staging.sh       # Deploy to staging
├── generators/
│   ├── model_generator.dart    # Generate model files
│   ├── provider_generator.dart # Generate provider files
│   └── screen_generator.dart   # Generate screen templates
└── utils/
    ├── json_to_dart.dart       # Convert JSON to Dart models
    ├── asset_generator.dart     # Generate asset references
    └── localization_helper.dart # Help with translations
```

---

## 📋 CODE GENERATION TEMPLATES

### Feature Template Generator
```dart
// tools/generators/feature_template.dart
class FeatureTemplate {
  static const String providerTemplate = '''
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../domain/repositories/{{feature_name}}_repository.dart';
import '../data/repositories/{{feature_name}}_repository_impl.dart';

class {{FeatureName}}Provider extends StateNotifier<{{FeatureName}}State> {
  {{FeatureName}}Provider(this.repository) : super(const {{FeatureName}}State.initial());

  final {{FeatureName}}Repository repository;

  // Add methods here
}

final {{featureName}}Provider = StateNotifierProvider<{{FeatureName}}Provider, {{FeatureName}}State>(
  (ref) => {{FeatureName}}Provider(ref.watch({{featureName}}RepositoryProvider)),
);

final {{featureName}}RepositoryProvider = Provider<{{FeatureName}}Repository>(
  (ref) => {{FeatureName}}RepositoryImpl(),
);
''';
}
```

---

## 🚀 BUILD CONFIGURATION

### Build Scripts
```bash
#!/bin/bash
# tools/scripts/build_runner.sh

echo "Running build runner..."
flutter packages pub run build_runner build --delete-conflicting-outputs

echo "Build runner completed!"
```

### Test Scripts
```bash
#!/bin/bash
# tools/scripts/test_runner.sh

echo "Running unit tests..."
flutter test test/unit/

echo "Running widget tests..."
flutter test test/widget/

echo "Running integration tests..."
flutter test test/integration/

echo "All tests completed!"
```

---

## 📱 PLATFORM CONFIGURATION

### Responsive Design Breakpoints
```dart
// lib/core/constants/breakpoints.dart
class Breakpoints {
  static const double mobile = 480;
  static const double tablet = 768;
  static const double desktop = 1024;
  static const double largeDesktop = 1440;

  static bool isMobile(double width) => width < mobile;
  static bool isTablet(double width) => width >= mobile && width < desktop;
  static bool isDesktop(double width) => width >= desktop;
}
```

### Device Configuration
```dart
// lib/core/constants/device_config.dart
class DeviceConfig {
  static const double defaultPadding = 16.0;
  static const double cardBorderRadius = 12.0;
  static const double buttonHeight = 48.0;
  static const double iconSize = 24.0;
  static const double appBarHeight = 56.0;
}
```

---

## 🔐 SECURITY CONFIGURATION

### Security Constants
```dart
// lib/core/constants/security.dart
class SecurityConstants {
  static const int maxLoginAttempts = 5;
  static const Duration lockoutDuration = Duration(minutes: 15);
  static const int sessionTimeoutMinutes = 30;
  static const int passwordMinLength = 8;
  static const int maxFileSize = 10 * 1024 * 1024; // 10MB
}
```

### Encryption Keys
```dart
// lib/core/constants/encryption.dart
class EncryptionKeys {
  // These should be stored securely and not hardcoded
  static const String storageKey = 'your_storage_encryption_key';
  static const String apiKey = 'your_api_encryption_key';
}
```

---

## 📊 PERFORMANCE CONFIGURATION

### Caching Strategy
```dart
// lib/core/constants/cache.dart
class CacheConstants {
  static const Duration shortCache = Duration(minutes: 5);
  static const Duration mediumCache = Duration(hours: 1);
  static const Duration longCache = Duration(days: 7);
  static const int maxCacheSize = 100 * 1024 * 1024; // 100MB
}
```

### Network Configuration
```dart
// lib/core/constants/network.dart
class NetworkConstants {
  static const Duration connectTimeout = Duration(seconds: 30);
  static const Duration receiveTimeout = Duration(seconds: 30);
  static const Duration sendTimeout = Duration(seconds: 30);
  static const int maxRetries = 3;
  static const Duration retryDelay = Duration(seconds: 1);
}
```

---

## 🎨 THEME CONFIGURATION

### Color System
```dart
// lib/app/theme/app_colors.dart
class AppColors {
  // Primary palette from EPVC design
  static const Color primaryBlue = Color(0xFF4A90E2);
  static const Color primaryTeal = Color(0xFF5AC8FA);
  static const Color primaryOrange = Color(0xFFFF9500);
  
  // Semantic colors
  static const Color success = Color(0xFF10B981);
  static const Color warning = Color(0xFFF59E0B);
  static const Color error = Color(0xFFEF4444);
  static const Color info = Color(0xFF3B82F6);
  
  // Neutral colors
  static const Color background = Color(0xFFF8F9FA);
  static const Color surface = Color(0xFFFFFFFF);
  static const Color onSurface = Color(0xFF1A1A1A);
  static const Color onSurfaceVariant = Color(0xFF6B7280);
}
```

### Typography System
```dart
// lib/app/theme/app_text_styles.dart
class AppTextStyles {
  static const TextStyle h1 = TextStyle(
    fontSize: 32,
    fontWeight: FontWeight.bold,
    height: 1.2,
  );
  
  static const TextStyle h2 = TextStyle(
    fontSize: 24,
    fontWeight: FontWeight.semiBold,
    height: 1.3,
  );
  
  static const TextStyle body = TextStyle(
    fontSize: 16,
    fontWeight: FontWeight.normal,
    height: 1.5,
  );
  
  static const TextStyle caption = TextStyle(
    fontSize: 12,
    fontWeight: FontWeight.normal,
    height: 1.4,
  );
}
```

---

## 📱 INTERNATIONALIZATION

### Supported Languages
```dart
// lib/l10n/app_localizations.dart
abstract class AppLocalizations {
  static const List<Locale> supportedLocales = [
    Locale('en'), // English
    Locale('pt'), // Portuguese
    Locale('es'), // Spanish
  ];
  
  static const Locale fallbackLocale = Locale('en');
}
```

### Translation Keys
```json
// lib/l10n/app_en.arb
{
  "app_name": "AI Study Assistant",
  "welcome_back": "Welcome back",
  "sign_in": "Sign In",
  "sign_up": "Sign Up",
  "ask_tutor": "Ask Tutor",
  "dashboard": "Dashboard",
  "progress": "Progress",
  "settings": "Settings"
}
```

---

## 🔧 DEVELOPMENT WORKFLOW

### Git Hooks
```bash
#!/bin/bash
# .git/hooks/pre-commit

echo "Running pre-commit checks..."

# Format code
dart format --set-exit-if-changed .

# Analyze code
dart analyze --fatal-infos

# Run tests
flutter test --coverage

echo "Pre-commit checks completed!"
```

### CI/CD Configuration
```yaml
# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.41.0'
      
      - name: Install dependencies
        run: flutter pub get
      
      - name: Run tests
        run: flutter test --coverage
      
      - name: Build app
        run: flutter build apk --release
```

---

## 📋 BEST PRACTICES

### Code Organization Rules
1. **Feature-first structure**: Group related files by feature
2. **Clean architecture**: Separate data, domain, and presentation layers
3. **Consistent naming**: Use descriptive, consistent naming conventions
4. **Small files**: Keep files focused and under 300 lines when possible
5. **Documentation**: Add comments for complex logic

### State Management Rules
1. **Riverpod providers**: Use appropriate provider types
2. **Immutable state**: Keep state immutable
3. **Async handling**: Use proper async/await patterns
4. **Error handling**: Handle errors gracefully
5. **Loading states**: Show loading indicators appropriately

### UI/UX Rules
1. **Responsive design**: Support all screen sizes
2. **Accessibility**: Follow accessibility guidelines
3. **Performance**: Optimize for smooth animations
4. **Consistency**: Use design system components
5. **User feedback**: Provide clear feedback for actions

---

## 🚀 DEPLOYMENT CONFIGURATION

### Environment Variables
```dart
// lib/core/constants/environment.dart
class Environment {
  static const bool isDebugMode = kDebugMode;
  static const bool isProductionMode = kReleaseMode;
  static const String apiBaseUrl = isDebugMode 
    ? 'http://localhost:8080' 
    : 'https://api.teachit.app';
}
```

### Build Variants
```yaml
# android/app/build.gradle
android {
    buildTypes {
        debug {
            applicationIdSuffix ".debug"
            debuggable true
        }
        profile {
            applicationIdSuffix ".profile"
            debuggable false
            signingConfig signingConfigs.debug
        }
        release {
            debuggable false
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            signingConfig signingConfigs.release
        }
    }
}
```

---

## 📊 MONITORING CONFIGURATION

### Analytics Setup
```dart
// lib/core/services/analytics_service.dart
class AnalyticsService {
  static void logScreenView(String screenName) {
    FirebaseAnalytics.instance.logScreenView(screenName: screenName);
  }
  
  static void logEvent(String name, {Map<String, Object>? parameters}) {
    FirebaseAnalytics.instance.logEvent(name, parameters: parameters);
  }
  
  static void setUserProperty(String name, String value) {
    FirebaseAnalytics.instance.setUserProperty(name: name, value: value);
  }
}
```

### Error Reporting
```dart
// lib/core/services/error_reporting_service.dart
class ErrorReportingService {
  static void recordError(dynamic error, StackTrace? stackTrace) {
    FirebaseCrashlytics.instance.recordError(error, stackTrace);
  }
  
  static void recordFlutterError(FlutterErrorDetails details) {
    FirebaseCrashlytics.instance.recordFlutterError(details);
  }
}
```

---

*Last Updated: 2026-05-06*
*Version: 1.0.0*
*Architecture Lead: Flutter Development Team*