base_flutter/claude.md

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:

🎨 flutter-widget-expert

• 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:

1. "Which of my specialists could handle this better?"
2. "Should I break this into parts for different specialists?"
3. "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

1. Use proper null safety practices
2. Implement proper error handling with Either type
3. Follow proper naming conventions
4. Use proper widget composition
5. Implement proper routing using GoRouter
6. Use proper form validation
7. Follow proper state management with Riverpod
8. Implement proper dependency injection using GetIt
9. Use proper asset management

Widget Guidelines

1. Keep widgets small and focused
2. Use const constructors when possible
3. Implement proper widget keys
4. Follow proper layout principles
5. Use proper widget lifecycle methods
6. Implement proper error boundaries
7. Use proper performance optimization techniques
8. Follow proper accessibility guidelines

Performance Guidelines

1. Use proper image caching
2. Implement proper list view optimization
3. Use proper build methods optimization
4. Follow proper state management patterns
5. Implement proper memory management
6. Use proper platform channels when needed
7. 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

1. Create feature directory under lib/features/
2. Implement data, domain, and presentation layers
3. Register providers in feature module
4. Add navigation routes
5. 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!