38 KiB
38 KiB
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
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
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
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
<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
// 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
#!/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
#!/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
// 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
// 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
// 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
// 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
// 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
// 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
// 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
// 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
// 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
// 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
#!/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
# .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
- Feature-first structure: Group related files by feature
- Clean architecture: Separate data, domain, and presentation layers
- Consistent naming: Use descriptive, consistent naming conventions
- Small files: Keep files focused and under 300 lines when possible
- Documentation: Add comments for complex logic
State Management Rules
- Riverpod providers: Use appropriate provider types
- Immutable state: Keep state immutable
- Async handling: Use proper async/await patterns
- Error handling: Handle errors gracefully
- Loading states: Show loading indicators appropriately
UI/UX Rules
- Responsive design: Support all screen sizes
- Accessibility: Follow accessibility guidelines
- Performance: Optimize for smooth animations
- Consistency: Use design system components
- User feedback: Provide clear feedback for actions
🚀 DEPLOYMENT CONFIGURATION
Environment Variables
// 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
# 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
// 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
// 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