From aefcae551645376aeeb9ddf516cf4705c0a9a029 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 16:02:57 +0000 Subject: [PATCH] Add comprehensive project plan for Bevy Tasks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This plan outlines the development of a local-first, cross-platform tasks application inspired by Google Tasks. Key features: - Cross-platform support (Windows, Linux, macOS, iOS, Android) - Fast startup time (< 500ms target) - Local file storage with optional WebDAV sync - Built with Bevy for future game-like UX polish - Phased development roadmap from MVP to advanced features The plan includes architecture design, technology stack, performance strategies, and detailed feature roadmap across 5 development phases. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 412 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..87ad1ee --- /dev/null +++ b/PLAN.md @@ -0,0 +1,412 @@ +# Bevy Tasks - Project Plan + +## Vision + +A local-first, cross-platform tasks application inspired by Google Tasks, built with Bevy for high performance and future game-like UX polish. The application will launch near-instantly on all platforms and support both local file storage and WebDAV synchronization. + +## Core Principles + +1. **Local-First**: All data is stored locally by default, with optional sync +2. **Performance**: Sub-second cold start time on all platforms +3. **Cross-Platform**: Native support for Windows, Linux, macOS, iOS, and Android +4. **Privacy**: User data stays on their devices and chosen storage locations +5. **Future-Proof**: Built on Bevy to enable advanced UI/UX features later + +## Target Platforms + +- **Desktop**: Windows, Linux, macOS +- **Mobile**: iOS, Android + +## Technology Stack + +### Core Framework +- **Bevy 0.16+**: Game engine providing cross-platform rendering and ECS architecture +- **bevy_ui**: For immediate UI components +- **bevy_egui**: Optional for more complex UI widgets (if needed) + +### Data Storage Layer +- **serde**: Serialization/deserialization +- **serde_json** or **rmp-serde**: JSON or MessagePack for task data +- **directories**: Cross-platform path handling +- **tokio**: Async runtime for I/O operations +- **reqwest** + **dav-client**: WebDAV support + +### Mobile Platform Support +- **bevy_mobile_example**: Reference for iOS/Android builds +- **cargo-apk**: Android builds +- **xcode**: iOS builds + +### Performance Optimization +- **Lazy loading**: Load only visible data +- **Asset preprocessing**: Minimize runtime overhead +- **Minimal dependencies**: Keep binary size small +- **Release optimizations**: LTO, strip symbols + +## Architecture + +### Data Model + +``` +Task { + id: Uuid, + title: String, + notes: Option, + status: TaskStatus, // NotStarted, InProgress, Completed + due_date: Option, + created_at: DateTime, + updated_at: DateTime, + parent_id: Option, // For subtasks + position: i32, // For ordering +} + +TaskList { + id: Uuid, + title: String, + tasks: Vec, + created_at: DateTime, + updated_at: DateTime, + position: i32, +} + +AppConfig { + storage_type: StorageType, // Local or WebDAV + local_path: Option, + webdav_url: Option, + webdav_credentials: Option, + theme: Theme, + last_sync: Option, +} +``` + +### Module Structure + +``` +bevy-tasks/ +├── src/ +│ ├── main.rs # Entry point +│ ├── app.rs # Bevy app setup +│ ├── data/ +│ │ ├── mod.rs +│ │ ├── models.rs # Task, TaskList, AppConfig +│ │ ├── repository.rs # Data access abstraction +│ │ └── storage/ +│ │ ├── mod.rs +│ │ ├── local.rs # Local file storage +│ │ └── webdav.rs # WebDAV client +│ ├── ui/ +│ │ ├── mod.rs +│ │ ├── screens/ +│ │ │ ├── task_list.rs +│ │ │ ├── task_detail.rs +│ │ │ └── settings.rs +│ │ └── components/ +│ │ ├── task_item.rs +│ │ ├── task_input.rs +│ │ └── list_selector.rs +│ ├── systems/ +│ │ ├── mod.rs +│ │ ├── input.rs # Input handling +│ │ ├── sync.rs # Background sync +│ │ └── navigation.rs # Screen navigation +│ └── resources/ +│ ├── mod.rs +│ └── app_state.rs # Global state management +├── assets/ +│ ├── fonts/ +│ └── icons/ +├── Cargo.toml +└── PLAN.md +``` + +### Storage Strategy + +#### Local Storage +- **Location**: Platform-specific app data directory + - Windows: `%APPDATA%/bevy-tasks/` + - Linux: `~/.local/share/bevy-tasks/` + - macOS: `~/Library/Application Support/bevy-tasks/` + - iOS: App sandbox documents directory + - Android: Internal storage app directory +- **Format**: JSON files (human-readable, debuggable) +- **Structure**: + ``` + data/ + ├── config.json + ├── lists/ + │ ├── {list-id-1}.json + │ └── {list-id-2}.json + └── metadata.json + ``` + +#### WebDAV Sync +- **Conflict Resolution**: Last-write-wins with timestamp +- **Sync Strategy**: + - On app start (if connected) + - On background timer (every 5 minutes when active) + - On task modification (debounced) +- **Offline Support**: All operations work offline, sync when online + +### Performance Strategy + +#### Fast Startup Requirements +1. **Minimal initialization**: Load only essential systems +2. **Lazy UI rendering**: Render visible items first +3. **Background loading**: Load non-critical data after first frame +4. **Asset optimization**: Embed minimal assets, load rest async +5. **Incremental parsing**: Stream large data files + +#### Startup Sequence +1. Initialize Bevy minimal plugins (< 50ms) +2. Load config from disk (< 20ms) +3. Render splash/empty state (first frame < 100ms) +4. Load task lists in background +5. Render tasks as they load +6. Start WebDAV sync (if configured) + +#### Memory Optimization +- Use `Vec` instead of `HashMap` for small collections +- Limit rendered tasks to visible viewport +- Unload non-visible screens from memory + +## Feature Roadmap + +### Phase 1: MVP (Weeks 1-4) +**Goal**: Basic local-first tasks app on desktop platforms + +**Features**: +- [ ] Single task list +- [ ] Create, read, update, delete tasks +- [ ] Mark tasks as complete/incomplete +- [ ] Local file storage (JSON) +- [ ] Basic UI (list view) +- [ ] Desktop support (Windows, Linux, macOS) + +**Deliverables**: +- Functional desktop app +- Data persists across sessions +- Sub-second startup time + +### Phase 2: Multiple Lists & Organization (Weeks 5-6) +**Goal**: Feature parity with basic Google Tasks functionality + +**Features**: +- [ ] Multiple task lists +- [ ] Switch between lists +- [ ] Subtasks support +- [ ] Due dates +- [ ] Task notes/descriptions +- [ ] Reorder tasks (drag & drop) +- [ ] Move tasks between lists + +**Deliverables**: +- Full task management functionality +- Improved UI/UX + +### Phase 3: WebDAV Sync (Weeks 7-9) +**Goal**: Enable cross-device synchronization + +**Features**: +- [ ] WebDAV client implementation +- [ ] Settings screen for storage configuration +- [ ] Sync status indicators +- [ ] Conflict resolution +- [ ] Offline mode with queue +- [ ] Manual sync trigger + +**Deliverables**: +- Working WebDAV sync +- Reliable conflict resolution +- Seamless offline/online transitions + +### Phase 4: Mobile Support (Weeks 10-14) +**Goal**: Deploy to iOS and Android + +**Features**: +- [ ] Touch-optimized UI +- [ ] iOS build pipeline +- [ ] Android build pipeline +- [ ] Mobile-specific UX (swipe gestures, etc.) +- [ ] Background sync on mobile +- [ ] Push notifications (optional) + +**Deliverables**: +- Working iOS app +- Working Android app +- Consistent UX across mobile and desktop + +### Phase 5: Polish & Advanced Features (Weeks 15+) +**Goal**: Differentiate from Google Tasks, leverage Bevy's capabilities + +**Features**: +- [ ] Themes and customization +- [ ] Advanced animations +- [ ] Keyboard shortcuts +- [ ] Search and filters +- [ ] Task templates +- [ ] Recurring tasks +- [ ] Statistics and insights +- [ ] Game-like achievement system (optional) +- [ ] Custom UI skins + +**Deliverables**: +- Polished, delightful UX +- Unique features not in Google Tasks + +## Development Guidelines + +### Performance Budgets +- **Cold start**: < 500ms on desktop, < 1s on mobile +- **First render**: < 100ms +- **Task creation**: < 50ms +- **Sync operation**: < 2s for typical dataset (< 1000 tasks) +- **Memory usage**: < 50MB on mobile, < 100MB on desktop + +### Testing Strategy +- **Unit tests**: Data models and business logic +- **Integration tests**: Storage layer operations +- **E2E tests**: Critical user flows +- **Performance tests**: Startup time, large datasets +- **Platform tests**: Verify each platform build + +### Build & Release +- **CI/CD**: GitHub Actions for all platforms +- **Desktop**: Direct downloads (AppImage, DMG, MSI) +- **Mobile**: App Store and Google Play +- **Version scheme**: Semantic versioning (0.1.0 → 1.0.0) + +## Technical Challenges & Solutions + +### Challenge 1: Fast Startup with Bevy +**Problem**: Bevy's plugin system can add overhead + +**Solutions**: +- Use `MinimalPlugins` instead of `DefaultPlugins` +- Add only required plugins (rendering, input) +- Lazy-load audio, asset server if not needed immediately +- Profile startup and optimize hot paths + +### Challenge 2: Mobile Platform Support +**Problem**: iOS and Android have different requirements + +**Solutions**: +- Use conditional compilation for platform-specific code +- Test early and often on real devices +- Follow platform guidelines (iOS HIG, Material Design) +- Use platform-specific file pickers and sharing + +### Challenge 3: WebDAV Reliability +**Problem**: Network can be unreliable, auth can be complex + +**Solutions**: +- Implement robust retry logic with exponential backoff +- Cache credentials securely (use platform keychains) +- Queue operations when offline +- Provide clear sync status to user +- Support multiple WebDAV servers (Nextcloud, ownCloud, etc.) + +### Challenge 4: Data Migration +**Problem**: Schema changes need to preserve user data + +**Solutions**: +- Version data format from day one +- Write migration scripts for each version bump +- Test migrations with real user data +- Backup before migration + +## Success Metrics + +### Performance +- ✓ Startup time < 500ms on mid-range devices +- ✓ 60 FPS UI on all platforms +- ✓ Handle 10,000+ tasks without performance degradation + +### User Experience +- ✓ Task creation in < 3 taps/clicks +- ✓ Zero data loss +- ✓ Sync conflicts rare and auto-resolved + +### Platform Support +- ✓ All 5 platforms working +- ✓ Consistent feature set across platforms +- ✓ Native feel on each platform + +## Dependencies + +### Core Dependencies +```toml +[dependencies] +bevy = "0.16" +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +uuid = { version = "1.0", features = ["serde", "v4"] } +chrono = { version = "0.4", features = ["serde"] } +directories = "5.0" +tokio = { version = "1.0", features = ["full"] } +anyhow = "1.0" + +# WebDAV support +reqwest = { version = "0.11", features = ["json"] } +# Note: Evaluate dav-client alternatives + +# Platform-specific +[target.'cfg(target_os = "android")'.dependencies] +# Android-specific deps + +[target.'cfg(target_os = "ios")'.dependencies] +# iOS-specific deps +``` + +## Getting Started + +### Prerequisites +- Rust 1.75+ (Bevy 0.16 requirement) +- Platform-specific tools: + - **iOS**: macOS + Xcode + - **Android**: Android SDK + NDK + +### Development Setup +```bash +# Clone repository +git clone +cd bevy-tasks + +# Run desktop version +cargo run + +# Build for release +cargo build --release + +# Run tests +cargo test + +# Build for Android +cargo apk build --release + +# Build for iOS (on macOS) +cargo build --target aarch64-apple-ios --release +``` + +## Questions & Decisions Needed + +1. **UI Framework**: Pure bevy_ui or bevy_egui for complex widgets? +2. **Data Format**: JSON (human-readable) or MessagePack (efficient)? +3. **Authentication**: How to securely store WebDAV credentials? +4. **Distribution**: Self-hosted only or aim for app stores? +5. **Backup Strategy**: Automatic local backups? Export functionality? + +## Resources + +- [Bevy Documentation](https://bevyengine.org/) +- [Bevy Mobile Examples](https://github.com/bevyengine/bevy/tree/main/examples/mobile) +- [WebDAV RFC 4918](https://datatracker.ietf.org/doc/html/rfc4918) +- [Google Tasks API](https://developers.google.com/tasks) (for feature reference) + +## License + +To be determined. + +--- + +**Last Updated**: 2025-10-26 +**Document Version**: 1.0 +**Status**: Planning Phase