A production-ready TODO application built with Flutter using Thomas Burkhart's PFA (Practical Flutter Architecture), featuring reactive state management with watch_it, command pattern with command_it, and local-first storage with Hive.
Phase 1A: ✅ COMPLETE - Foundation & Business Logic Phase 1B: ⏳ Pending - UI Implementation Phase 2: ⏳ Planned - Firebase Integration
- rules.md - Complete architecture guidelines and best practices
- plan.md - 22-step implementation plan with milestones
- PHASE1_PROGRESS.md - Detailed completion log for Phase 1
- TEST_SUMMARY.md - Comprehensive test coverage report
This app follows Thomas Burkhart's pragmatic three-layer architecture:
┌─────────────────────────────────────┐
│ Views Layer (UI) │
│ - WatchingWidgets with watch_it │
│ - Self-responsible pages │
│ - Reactive state updates │
└─────────────────────────────────────┘
↕
┌─────────────────────────────────────┐
│ Managers Layer (Logic) │
│ - Business logic with Commands │
│ - ValueNotifiers for state │
│ - Validation & coordination │
└─────────────────────────────────────┘
↕
┌─────────────────────────────────────┐
│ Services Layer (I/O) │
│ - Hive local storage │
│ - Firebase (Phase 2) │
│ - Pure data transformation │
└─────────────────────────────────────┘
- State Management:
watch_itv1.7.0 - Reactive widgets without boilerplate - Command Pattern:
command_itv8.0.0 - Wraps operations with execution state - Dependency Injection:
get_itv8.0.0 - Service locator pattern - Local Storage:
hivev2.2.3 - Fast NoSQL database - ID Generation:
uuidv4.0.0 - Unique identifiers
- Flutter SDK 3.9.0 or higher
- Dart 3.0+ (included with Flutter)
-
Clone the repository
cd todoit -
Install dependencies
flutter pub get
-
Generate code
dart run build_runner build --delete-conflicting-outputs
-
Run the app
# Chrome (recommended for development) flutter run -d chrome # iOS Simulator flutter run -d ios # Android Emulator flutter run -d android
# Run all tests
flutter test
# Run with coverage
flutter test --coverage
# Run specific test file
flutter test test/models/todo_test.dartTest Results: ✅ 69/69 passing (~98% coverage)
lib/
├── main.dart # App entry point with Hive initialization
├── locator.dart # Dependency injection setup
├── features/
│ ├── todos/
│ │ ├── models/
│ │ │ ├── todo.dart # Domain model
│ │ │ ├── todo_dto.dart # Hive DTO
│ │ │ └── todo_dto.g.dart # Generated Hive adapter
│ │ ├── managers/
│ │ │ └── todo_manager.dart # Business logic with Commands
│ │ └── views/ # [Phase 1B - TODO]
│ │ ├── todo_list_view.dart
│ │ └── todo_form_view.dart
│ └── settings/
│ ├── managers/ # [Phase 1B - TODO]
│ └── views/ # [Phase 1B - TODO]
├── services/
│ └── storage/
│ └── hive_storage_service.dart # Local storage implementation
└── shared/
├── widgets/ # [Phase 1B - TODO]
└── utils/ # [Phase 1B - TODO]
test/
├── models/
│ └── todo_test.dart # 17 tests ✅
├── services/
│ └── hive_storage_service_test.dart # 24 tests ✅
└── managers/
└── todo_manager_test.dart # 28 tests ✅
- ✅ Todo CRUD operations (Create, Read, Update, Delete)
- ✅ Toggle todo completion status
- ✅ Filter todos (All / Active / Completed)
- ✅ Clear completed todos
- ✅ Persistent local storage with Hive
- ✅ Automatic sorting (newest first)
- ✅ Input validation (title required)
- ✅ UUID generation for unique IDs
- ✅ Timestamp tracking (created/updated)
- ✅ Reactive state management
- ✅ Command pattern for operations
- ⏳ Todo list view with filters
- ⏳ Add/Edit todo form
- ⏳ Swipe to delete
- ⏳ Dark mode support
- ⏳ Settings screen
- ⏳ Empty states
- ⏳ Loading indicators
- ⏳ Error handling UI
- ⏳ Firebase authentication
- ⏳ Cloud Firestore sync
- ⏳ Offline-first architecture
- ⏳ Conflict resolution
- ⏳ Multi-device sync
| Component | Tests | Coverage | Status |
|---|---|---|---|
| Todo Model | 17 | 100% | ✅ |
| HiveStorageService | 24 | 100% | ✅ |
| TodoManager | 28 | ~95% | ✅ |
| Total | 69 | ~98% | ✅ |
- ✅ Data model conversions (Todo ↔ DTO)
- ✅ All CRUD operations
- ✅ Business logic (add, update, delete, toggle, filter)
- ✅ Computed properties (counts, checks)
- ✅ Edge cases (empty data, null values, large datasets)
- ✅ Error scenarios (validation, not found)
See TEST_SUMMARY.md for detailed coverage report.
flutter analyzeResult: ✅ No issues found!
Hive adapters are generated using build_runner:
# Generate once
dart run build_runner build
# Watch for changes
dart run build_runner watch
# Delete conflicting outputs
dart run build_runner build --delete-conflicting-outputs- Update Domain Model (
lib/features/todos/models/) - Update DTO (if storage schema changes)
- Run Code Generation (
dart run build_runner build) - Update Service Layer (if I/O operations needed)
- Update Manager (business logic and commands)
- Write Tests (aim for >90% coverage)
- Update Views (UI implementation)
- Run Tests (
flutter test) - Run Analyzer (
flutter analyze)
- ✅ Always prefer editing existing files over creating new ones
- ✅ Follow PFA layer separation (Views → Managers → Services)
- ✅ Use Commands for state-modifying operations
- ✅ Use watch_it for reactive UI updates
- ✅ Write tests before implementation (TDD encouraged)
- ✅ Keep ValueNotifiers in Managers, not Views
- ✅ Validate in Manager layer, not Views
- ✅ Never modify state directly, always through Commands
See rules.md for complete architecture guidelines.
Problem: Tests failing with "ValueNotifier used after disposal" Solution: Ensure proper async handling in setUp/tearDown with delays
Problem: Build runner fails
Solution: Run with --delete-conflicting-outputs flag
Problem: Hive adapter not found
Solution: Run dart run build_runner build and restart app
Problem: Import errors for generated files
Solution: Run flutter pub get then dart run build_runner build
This is a learning project following PFA architecture principles. Key areas for contribution:
- Phase 1B: Implement UI layer with
WatchingWidget - Phase 2: Add Firebase integration
- Testing: Add widget and integration tests
- Documentation: Improve code comments and examples
This project is created for educational purposes to demonstrate PFA architecture.
- Thomas Burkhart for the PFA architecture and watch_it/command_it packages
- Flutter Team for the amazing framework
- Hive developers for the fast local database
- Lines of Code: ~800 (excluding tests and generated files)
- Test Lines: ~1,100
- Test Coverage: ~98%
- Build Time: ~30s (web)
- Test Time: ~12s
- Dependencies: 8 main, 5 dev
- Implement Todo List View (Phase 1B - Step 8)
- Implement Todo Form (Phase 1B - Step 9)
- Add Navigation (Phase 1B - Step 10)
- Create Shared Widgets (Phase 1B - Step 11)
- Add Widget Tests (Phase 1B - Steps 13-14)
See plan.md for the complete roadmap.
Built with ❤️ using Flutter and PFA Architecture
For questions or issues, refer to the documentation files in this repository.