# 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
```
learn_it/
โโโ 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: learn_it
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.learnit'
compileSdkVersion flutter.compileSdkVersion
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = '17'
}
defaultConfig {
applicationId "com.example.learnit"
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
CFBundleDisplayName
Learn It
CFBundleIdentifier
com.example.learnit
CFBundleVersion
1.0
UISupportedInterfaceOrientations
UIInterfaceOrientationPortrait
UIInterfaceOrientationLandscapeLeft
UIInterfaceOrientationLandscapeRight
UIStatusBarStyle
UIStatusBarStyleLightContent
NSCameraUsageDescription
This app needs camera access for profile photos
NSPhotoLibraryUsageDescription
This app needs photo library access for profile photos
```
---
## ๐งช 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 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.learnit.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? 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*