Historical documentation files - superseded by consolidated guides
These documentation files have been archived and are kept for historical reference only. They have been superseded by the new consolidated documentation in the parent docs/ folder.
For current guidelines, please refer to:
Original Focus: Riverpod + Supabase Integration
Key Topics:
- Riverpod state management (AsyncNotifierProvider)
- Supabase backend integration
- Component-based architecture
- Error handling with AsyncValue
- SelectableText.rich for error display
Why Archived:
- Too specific to one tech stack (Riverpod + Supabase)
- Didn't address project size considerations
- Lacked comparison with other approaches
- Missing testing and security guidance
What Was Preserved:
- Error handling patterns → Core Principles
- Component organization → Core Principles
- Riverpod examples → State Management Guide (as alternative to Provider/BLoC)
Original Focus: Clean Code Principles with Dart/Flutter
Key Topics:
- Explicit type declarations
- Descriptive naming conventions
- Composition over inheritance
- Short, focused functions
- Early returns
- Trailing commas
Why Archived:
- Excellent principles but lacked practical examples
- No ✅ DO / ❌ DON'T comparisons
- Missing state management guidance
- No testing or security coverage
What Was Preserved:
- All clean code principles → Core Principles
- Enhanced with practical examples and anti-patterns
- Integrated with Flutter-specific best practices
Original Focus: BLoC Pattern + Firebase Integration
Key Topics:
- BLoC state management
- Firebase backend integration
- Event-driven architecture
- State management with Freezed
- Error handling with state classes
Why Archived:
- Too specific to Firebase backend
- Didn't explain when to use BLoC vs simpler approaches
- Lacked migration strategies
- Missing small/medium project guidance
What Was Preserved:
- BLoC patterns → State Management Guide
- Event-driven architecture → State Management Guide
- Freezed usage → State Management Guide
- Now includes guidance on when to use BLoC (large projects only)
Original Focus: Clean Architecture with flutter_bloc and Dartz
Key Topics:
- Clean Architecture layers (Domain, Data, Presentation)
- Dependency injection with GetIt
- Error handling with Dartz Either<Failure, Success>
- Repository pattern
- Use cases
- Strict separation of concerns
Why Archived:
- Excellent for enterprise apps but overkill for small/medium projects
- No guidance on when this complexity is needed
- Steep learning curve for beginners
- Missing simpler alternatives
What Was Preserved:
- Clean Architecture principles → Core Principles
- Repository pattern → Core Principles
- Error handling patterns → Core Principles
- BLoC with Clean Architecture → State Management Guide
- Now positioned as enterprise/large project approach
New Approach:
- Read Core Principles for universal best practices
- Evaluate project size:
- Small project? Consider migrating to Provider or staying with Riverpod
- Medium project? Provider is recommended, but Riverpod works too
- Large project? Consider BLoC for better team scalability
- Review State Management Guide for your chosen approach
- Add testing following Testing Guide
- Implement security from Security Best Practices
New Approach:
- Continue following clean code principles from Core Principles
- Now enhanced with:
- ✅ DO / ❌ DON'T examples
- Performance optimization patterns
- Flutter-specific best practices
- Add state management from State Management Guide
- Implement testing from Testing Guide
- Add security from Security Best Practices
New Approach:
- Read Core Principles for foundation
- Evaluate if BLoC is right for your project size:
- Small project? Consider migrating to setState/Provider
- Medium project? Consider Provider for less boilerplate
- Large project? Continue with BLoC
- Follow State Management Guide BLoC section
- Includes migration strategies if downsizing
- Add comprehensive testing from Testing Guide
- Implement security from Security Best Practices
New Approach:
- Read Core Principles for foundation
- Evaluate if Clean Architecture is needed:
- Small/Medium project? Likely overkill, consider simpler architecture
- Large/Enterprise project? Continue with Clean Architecture
- Follow State Management Guide for BLoC integration
- Implement comprehensive testing from Testing Guide
- Add security from Security Best Practices
| Aspect | Legacy Docs | New Docs |
|---|---|---|
| Project Size Guidance | ❌ One-size-fits-all | ✅ Tiered approach (small/medium/large) |
| Practical Examples | ✅ Extensive ✅ DO / ❌ DON'T examples | |
| State Management | ✅ Clear decision tree and migration paths | |
| Testing | ❌ Missing | ✅ Comprehensive testing guide |
| Security | ❌ Missing | ✅ Complete security best practices |
| Code Examples | ✅ Complete, runnable examples | |
| Migration Strategies | ❌ None | ✅ Step-by-step migration guides |
| Comparison Matrix | ❌ None | ✅ Feature comparison tables |
- Four separate, sometimes conflicting documents
- Each advocated for specific tech stack
- No guidance on when to use which approach
- Missing critical topics (testing, security)
- Limited practical examples
- Consolidated, cohesive documentation
- Tiered recommendations based on project size
- Clear decision trees and migration paths
- Comprehensive coverage (principles, state, testing, security)
- Extensive ✅ DO / ❌ DON'T examples with explanations
For the most up-to-date Flutter development guidelines, please refer to:
- Main Documentation Index - Start here
- Core Principles - Universal best practices
- State Management Guide - Choose the right approach
- Testing Guide - Testing pyramid and strategies
- Security Best Practices - Protect your app
Archived: 2025-11-14
Reason: Consolidated into comprehensive, tiered documentation
Status: Historical reference only