Files

2025-09-26 15:17:28 +07:00

13 KiB

Raw Blame History

Flutter App Expert Guidelines

Flexibility Notice

Important: This is a recommended project structure, but be flexible and adapt to existing project structures. Do not enforce these structural patterns if the project follows a different organization. Focus on maintaining consistency with the existing project architecture while applying Flutter best practices.

🤖 SUBAGENT DELEGATION SYSTEM 🤖

CRITICAL: BE PROACTIVE WITH SUBAGENTS! YOU HAVE SPECIALIZED EXPERTS AVAILABLE!

🚨 DELEGATION MINDSET

Instead of thinking "I'll handle this myself" Think: "Which specialist is BEST suited for this task?"

📋 AVAILABLE SPECIALISTS

You have access to these expert subagents - USE THEM PROACTIVELY:

MUST BE USED for: Custom widgets, UI components, layouts, animations, Material 3 design
Triggers: "create widget", "build UI", "design component", "layout", "animation"

🔄 riverpod-expert

MUST BE USED for: State management, providers, reactive programming, async operations
Triggers: "state management", "provider", "riverpod", "async state", "data flow"

🗄️ hive-expert

MUST BE USED for: Local database, caching, data models, Hive operations, storage
Triggers: "database", "cache", "hive", "local storage", "data persistence"

🌐 api-integration-expert

MUST BE USED for: HTTP clients, API calls, error handling, network operations
Triggers: "API", "HTTP", "network", "dio", "REST", "endpoint"

🏗️ architecture-expert

MUST BE USED for: Clean architecture, feature structure, dependency injection, project organization
Triggers: "architecture", "structure", "organization", "clean code", "refactor"

⚡ performance-expert

MUST BE USED for: Optimization, image caching, memory management, build performance
Triggers: "performance", "optimization", "memory", "cache", "slow", "lag"

🎯 DELEGATION STRATEGY

BEFORE starting ANY task, ASK YOURSELF:

"Which of my specialists could handle this better?"
"Should I break this into parts for different specialists?"
"Would a specialist complete this faster and better?"

💼 WORK BALANCE RECOMMENDATION:

Simple Tasks (20%): Handle independently - quick fixes, minor updates
Complex Tasks (80%): Delegate to specialists for expert-level results

🔧 HOW TO DELEGATE

# Explicit delegation examples:  
> Use the flutter-widget-expert to create a custom movie card widget  
> Have the riverpod-expert design the state management for the media grid  
> Ask the hive-expert to create the database schema for caching  
> Use the api-integration-expert to implement the Sonarr API client  
> Have the architecture-expert review the feature structure  
> Ask the performance-expert to optimize the image loading

Flutter Best Practices

Adapt to existing project architecture while maintaining clean code principles
Use Flutter 3.x features and Material 3 design
Implement clean architecture with Riverpod pattern
Follow proper state management principles
Use proper dependency injection
Implement proper error handling
Follow platform-specific design guidelines
Use proper localization techniques

Preferred Project Structure

Note: This is a reference structure. Adapt to the project's existing organization.

lib/  
 core/  
	 constants/  
	 theme/  
	 utils/  
	 widgets/  
 features/  
	 feature_name/  
		 data/  
			 datasources/  
			 models/  
			 repositories/  
		 domain/  
			 entities/  
			 repositories/  
			 usecases/  
		 presentation/  
			 providers/  
			 pages/  
			 widgets/  
 l10n/  
 main.dart  
test/  
 unit/  
 widget/  
 integration/

Coding Guidelines

Use proper null safety practices
Implement proper error handling with Either type
Follow proper naming conventions
Use proper widget composition
Implement proper routing using GoRouter
Use proper form validation
Follow proper state management with Riverpod
Implement proper dependency injection using GetIt
Use proper asset management

Keep widgets small and focused
Use const constructors when possible
Implement proper widget keys
Follow proper layout principles
Use proper widget lifecycle methods
Implement proper error boundaries
Use proper performance optimization techniques
Follow proper accessibility guidelines

Performance Guidelines

Use proper image caching
Implement proper list view optimization
Use proper build methods optimization
Follow proper state management patterns
Implement proper memory management
Use proper platform channels when needed
Follow proper compilation optimization techniques

Refactoring Instructions

When refactoring code:

Always maintain existing project structure patterns
Prioritize consistency with current codebase
Apply Flutter best practices without breaking existing architecture
Focus on incremental improvements
Ensure all changes maintain backward compatibility

App Context - Base Flutter Application

About This App

A foundational Flutter mobile application with a robust architecture designed for scalability and maintainability. This base app provides the essential infrastructure components needed for any modern Flutter application.

Target Users

Developers building Flutter applications
Teams requiring a solid architectural foundation
Projects needing consistent patterns and practices

Core Infrastructure

Project Structure

Core Layer: Essential utilities, constants, and shared functionality
Network Layer: HTTP clients, API infrastructure, and connectivity management
Theme Layer: Design system, colors, typography, and Material 3 implementation
Error Handling: Centralized error management and user feedback

Architecture Foundation

lib/  
 core/  
 constants/      # App-wide constants and configuration  
 network/        # HTTP clients, interceptors, API base classes  
 theme/          # Design system, Material 3 theme configuration  
 errors/         # Custom exceptions, error handling utilities  
 utils/          # Helper functions, extensions, formatters  
 widgets/        # Shared UI components  
 main.dart

Technical Stack

Flutter & Dart

Flutter 3.x with Material 3 design
Dart 3.x with null safety
Modern Flutter development practices

Architecture & State Management

Clean architecture with feature-first structure
Riverpod for state management (NOT BLoC)
Repository pattern for data layer
Hive for local database and caching

Core Dependencies

flutter_riverpod / riverpod - State management
hive / hive_flutter - Local database and caching
dio - HTTP client for API calls
go_router - Navigation and routing
flutter_secure_storage - Secure storage for sensitive data
cached_network_image - Image caching and optimization
json_annotation / freezed - Model serialization
hive_generator - Code generation for Hive adapters

Core Components

Constants Layer (`lib/core/constants/`)

API Constants: Base URLs, endpoints, timeouts
App Constants: Version info, feature flags, defaults
UI Constants: Spacing, dimensions, animation durations
Storage Constants: Hive box names, cache keys

Network Layer (`lib/core/network/`)

HTTP Client: Configured Dio instance with interceptors
API Base Classes: Generic API response handling
Network Info: Connectivity status and monitoring
Request/Response Models: Base classes for API communication
Error Handling: HTTP error codes and network exceptions

Theme Layer (`lib/core/theme/`)

App Theme: Material 3 design system implementation
Color Schemes: Light/dark mode color definitions
Typography: Text styles and font configurations
Component Themes: Button, card, input field customizations
Responsive Design: Screen size breakpoints and adaptive layouts

Error Handling (`lib/core/errors/`)

Custom Exceptions: Business logic and network exceptions
Failure Classes: Standardized error representations
Error Messages: User-friendly error text and localization
Logging: Error tracking and debugging utilities

State Management Architecture (Riverpod)

Provider Structure

providers/  
 network_providers.dart     # HTTP clients, connectivity  
 theme_providers.dart       # Theme state, dark mode  
 storage_providers.dart     # Hive boxes, secure storage  
 app_providers.dart         # Global app state

Modern Provider Types

Provider: For dependency injection and immutable values (Dio, Hive boxes, constants)
FutureProvider: For async operations and initialization
StreamProvider: For reactive data streams (connectivity, real-time updates)
NotifierProvider: For synchronous mutable state management
AsyncNotifierProvider: For async mutable state with loading/error handling
StreamNotifierProvider: For stream-based mutable state management

Hive Database Foundation

Core Boxes

appSettingsBox: User preferences and app configuration
cacheBox: General purpose caching
userDataBox: User-specific data storage

Base Models with Hive Adapters

AppSettings - User preferences, theme, language
CacheItem - Generic caching wrapper
UserPreferences - User-specific settings

Network Infrastructure

HTTP Client Configuration

Base URL Management: Environment-specific endpoints
Interceptors: Authentication, logging, error handling
Timeout Configuration: Request/response timeouts
Retry Logic: Automatic retry for failed requests
Certificate Pinning: Security for production APIs

API Response Patterns

Standardized Responses: Consistent API response structure
Error Mapping: Convert HTTP errors to domain exceptions
Loading States: AsyncValue patterns with Riverpod
Caching Strategy: Network-first with Hive fallback

UI Foundation

Core Widgets (`lib/core/widgets/`)

Loading Indicators: Consistent loading UI patterns
Error Widgets: Standardized error display components
Empty States: No data found UI patterns
Buttons: Custom button components following Material 3
Input Fields: Form components with validation
Cards: Reusable card layouts

Theme Implementation

Material 3: Full Material You design system
Dynamic Colors: System color extraction support
Dark Mode: Seamless light/dark theme switching
Accessibility: WCAG compliant color contrast
Typography: Responsive text scaling

Error Handling Strategy

Exception Hierarchy

abstract class AppException implements Exception {  
 final String message; final String? code;}  
  
class NetworkException extends AppException {}  
class CacheException extends AppException {}  
class ValidationException extends AppException {}

User Feedback

Snackbars: Quick notifications and confirmations
Error Dialogs: Detailed error information
Retry Mechanisms: User-initiated retry actions
Offline Indicators: Network status feedback

Performance Foundation

Core Optimizations

Widget Performance: Const constructors, proper keys
Image Management: Caching, compression, lazy loading
Memory Management: Proper disposal patterns
Build Optimization: Efficient widget rebuilds
Database Performance: Optimized Hive queries

Monitoring

Performance Tracking: Frame rate monitoring
Memory Usage: Leak detection and optimization
Network Monitoring: Request timing and failures
Error Tracking: Crash reporting and analysis

Security Foundation

Data Protection

Secure Storage: Encrypted storage for sensitive data
API Security: Token management, refresh logic
Input Validation: Sanitization and validation utilities
Certificate Pinning: Network security measures
Encryption: Local data encryption capabilities

Development Guidelines

Code Organization

Feature-first architecture for scalability
Consistent naming conventions
Proper dependency injection patterns
Clean separation of concerns
Comprehensive error handling

Testing Strategy

Unit tests for business logic and utilities
Widget tests for UI components
Integration tests for full user flows
Mock implementations for external dependencies
Test coverage monitoring and reporting

Extensibility

Adding New Features

Create feature directory under lib/features/
Implement data, domain, and presentation layers
Register providers in feature module
Add navigation routes
Update theme if needed

Configuration Management

Environment-specific configurations
Feature flag implementation
API endpoint management
Build variant support
Configuration validation

This base application provides a solid foundation for building scalable Flutter applications with proper architecture, error handling, and performance optimization built-in from the start.
Remember: ALWAYS DELEGATE TO SPECIALISTS FOR BETTER RESULTS!

13 KiB Raw Blame History