SteelDynamite/onyx-tasks
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add comprehensive project plan for Bevy Tasks

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Claude 2025-10-26 16:02:57 +00:00
parent a5351bd8e8
commit aefcae5516
No known key found for this signature in database
1 changed files with 412 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

412
PLAN.md Normal file
View file

@ -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<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
```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 <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](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