Skip to content

README.md

Latest commit

 

History

History
353 lines (255 loc) · 9.85 KB

README.md

File metadata and controls

353 lines (255 loc) · 9.85 KB

TodoIt - A Modern Flutter TODO App

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.

🎯 Project Status

Phase 1A: ✅ COMPLETE - Foundation & Business Logic Phase 1B: ⏳ Pending - UI Implementation Phase 2: ⏳ Planned - Firebase Integration

📚 Documentation

🏗️ Architecture

PFA (Practical Flutter Architecture)

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         │
└─────────────────────────────────────┘

Key Technologies

  • State Management: watch_it v1.7.0 - Reactive widgets without boilerplate
  • Command Pattern: command_it v8.0.0 - Wraps operations with execution state
  • Dependency Injection: get_it v8.0.0 - Service locator pattern
  • Local Storage: hive v2.2.3 - Fast NoSQL database
  • ID Generation: uuid v4.0.0 - Unique identifiers

🚀 Getting Started

Prerequisites

  • Flutter SDK 3.9.0 or higher
  • Dart 3.0+ (included with Flutter)

Installation

  1. Clone the repository

    cd todoit

  2. Install dependencies

    flutter pub get

  3. Generate code

    dart run build_runner build --delete-conflicting-outputs

  4. Run the app

    # Chrome (recommended for development)
flutter run -d chrome

# iOS Simulator
flutter run -d ios

# Android Emulator
flutter run -d android

Running Tests

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

# Run specific test file
flutter test test/models/todo_test.dart

Test Results: ✅ 69/69 passing (~98% coverage)

📁 Project Structure

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 ✅

✨ Features

Implemented (Phase 1A)

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

Planned (Phase 1B - UI)

  • ⏳ Todo list view with filters
  • ⏳ Add/Edit todo form
  • ⏳ Swipe to delete
  • ⏳ Dark mode support
  • ⏳ Settings screen
  • ⏳ Empty states
  • ⏳ Loading indicators
  • ⏳ Error handling UI

Planned (Phase 2 - Cloud)

  • ⏳ Firebase authentication
  • ⏳ Cloud Firestore sync
  • ⏳ Offline-first architecture
  • ⏳ Conflict resolution
  • ⏳ Multi-device sync

🧪 Testing

Test Coverage

Component Tests Coverage Status
Todo Model 17 100% ✅
HiveStorageService 24 100% ✅
TodoManager 28 ~95% ✅
Total 69 ~98% ✅

What's Tested

  • ✅ 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.

🎯 Code Quality

Static Analysis

flutter analyze

Result: ✅ No issues found!

Code Generation

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

🔧 Development Workflow

Adding a New Feature

  1. Update Domain Model (lib/features/todos/models/)
  2. Update DTO (if storage schema changes)
  3. Run Code Generation (dart run build_runner build)
  4. Update Service Layer (if I/O operations needed)
  5. Update Manager (business logic and commands)
  6. Write Tests (aim for >90% coverage)
  7. Update Views (UI implementation)
  8. Run Tests (flutter test)
  9. Run Analyzer (flutter analyze)

Best Practices

  • ✅ 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.

📖 Learning Resources

PFA Architecture

Dependencies Documentation

🛠️ Troubleshooting

Common Issues

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

🤝 Contributing

This is a learning project following PFA architecture principles. Key areas for contribution:

  1. Phase 1B: Implement UI layer with WatchingWidget
  2. Phase 2: Add Firebase integration
  3. Testing: Add widget and integration tests
  4. Documentation: Improve code comments and examples

📝 License

This project is created for educational purposes to demonstrate PFA architecture.

🙏 Acknowledgments

  • 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

📊 Project Stats

  • 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

🚦 Next Steps

  1. Implement Todo List View (Phase 1B - Step 8)
  2. Implement Todo Form (Phase 1B - Step 9)
  3. Add Navigation (Phase 1B - Step 10)
  4. Create Shared Widgets (Phase 1B - Step 11)
  5. 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.