onyx-tasks/PLAN.md

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<String>,
    status: TaskStatus,  // NotStarted, InProgress, Completed
    due_date: Option<DateTime>,
    created_at: DateTime,
    updated_at: DateTime,
    parent_id: Option<Uuid>,  // For subtasks
    position: i32,  // For ordering
}

TaskList {
    id: Uuid,
    title: String,
    tasks: Vec<Task>,
    created_at: DateTime,
    updated_at: DateTime,
    position: i32,
}

AppConfig {
    storage_type: StorageType,  // Local or WebDAV
    local_path: Option<PathBuf>,
    webdav_url: Option<String>,
    webdav_credentials: Option<Credentials>,
    theme: Theme,
    last_sync: Option<DateTime>,
}

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

[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

# Clone repository
git clone <repository-url>
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
• Bevy Mobile Examples
• WebDAV RFC 4918
• Google Tasks API (for feature reference)

License

To be determined.

---

Last Updated: 2025-10-26 Document Version: 1.0 Status: Planning Phase