215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# Phase 3: Cross-Platform Flutter Presentation Layer
|
|
|
|
## Status: Pending Phase 2 Completion
|
|
|
|
**Phase Goal:** Build the complete Flutter UI shell for Windows, Linux, and Android, integrating the Rust FFI bridge with all four primary views (Eisenhower Matrix, Calendar Time-Blocking, Kanban/Gantt, Notes), and establish the BLoC state management architecture.
|
|
|
|
**Prerequisites:** Phase 2 complete ✅
|
|
**Estimated Complexity:** Very High
|
|
**Blocking:** Phase 4 (AI output must render in UI), Phase 5 (final integration testing)
|
|
|
|
---
|
|
|
|
## Task 3.1 — Run FFI Code Generation & Establish Flutter Architecture
|
|
|
|
- [ ] **Task 3.1**: Run `flutter_rust_bridge_codegen generate` and establish the Flutter project architecture:
|
|
- Install `flutter_rust_bridge_codegen@2.7.0`: `cargo install flutter_rust_bridge_codegen@2.7.0`
|
|
- Run `flutter_rust_bridge_codegen generate` from workspace root
|
|
- Verify generated files exist:
|
|
- `crates/chronogrid_ffi/src/frb_generated.rs`
|
|
- `apps/chronogrid_flutter/lib/src/rust/frb_generated.dart`
|
|
- `apps/chronogrid_flutter/lib/src/rust/api/*.dart`
|
|
- Uncomment `mod frb_generated;` in `crates/chronogrid_ffi/src/lib.rs`
|
|
- Add Flutter dependencies to `pubspec.yaml`:
|
|
- `flutter_bloc: ^8.1.0` — BLoC state management
|
|
- `equatable: ^2.0.5` — Value equality for BLoC states
|
|
- `get_it: ^7.6.0` — Service locator / dependency injection
|
|
- `go_router: ^14.0.0` — Declarative routing
|
|
- `intl: ^0.19.0` — Date/time formatting
|
|
- `path_provider: ^2.1.0` — Platform-specific file paths
|
|
- `shared_preferences: ^2.2.0` — Lightweight local settings
|
|
- Establish directory structure under `apps/chronogrid_flutter/lib/`:
|
|
```
|
|
lib/
|
|
├── main.dart
|
|
├── app.dart # MaterialApp + GoRouter setup
|
|
├── src/
|
|
│ ├── rust/ # FRB generated (do not edit)
|
|
│ ├── core/
|
|
│ │ ├── engine_service.dart # Wraps FFI init/close lifecycle
|
|
│ │ ├── di.dart # GetIt service locator setup
|
|
│ │ └── router.dart # GoRouter route definitions
|
|
│ ├── features/
|
|
│ │ ├── tasks/ # Task BLoC + repository + UI
|
|
│ │ ├── notes/ # Notes BLoC + repository + UI
|
|
│ │ ├── calendar/ # Calendar BLoC + repository + UI
|
|
│ │ ├── eisenhower/ # Eisenhower BLoC + UI
|
|
│ │ ├── kanban/ # Kanban BLoC + UI
|
|
│ │ ├── sync/ # P2P sync status BLoC + UI
|
|
│ │ └── settings/ # Settings BLoC + UI
|
|
│ └── shared/
|
|
│ ├── widgets/ # Reusable UI components
|
|
│ ├── theme/ # Material 3 theme tokens
|
|
│ └── models/ # Dart model classes (DTOs)
|
|
```
|
|
- Run `flutter pub get` and `flutter analyze` — zero errors
|
|
|
|
---
|
|
|
|
## Task 3.2 — Engine Initialization & Onboarding Flow
|
|
|
|
- [ ] **Task 3.2**: Implement the engine initialization and first-run onboarding flow:
|
|
- Implement `EngineService` in `lib/src/core/engine_service.dart`:
|
|
- `Future<void> initialize()` — derives master key via FFI, opens database, starts P2P swarm
|
|
- `Future<void> shutdown()` — gracefully closes engine
|
|
- `bool get isInitialized`
|
|
- Implement `OnboardingBloc` with states: `OnboardingInitial`, `OnboardingPassphraseEntry`, `OnboardingKeyDerivationInProgress`, `OnboardingComplete`, `OnboardingError`
|
|
- Implement `OnboardingScreen` — passphrase entry with strength indicator, namespace setup (Personal/Engineering/Custom), node ID display
|
|
- Implement `SplashScreen` — checks for existing keychain credential, routes to onboarding or main shell
|
|
- Unit tests: `OnboardingBloc` state transitions
|
|
- Widget tests: `OnboardingScreen` renders correctly, passphrase field validation
|
|
|
|
---
|
|
|
|
## Task 3.3 — Task Repository & BLoC Layer
|
|
|
|
- [ ] **Task 3.3**: Implement the task data layer and BLoC:
|
|
- Implement `TaskRepository` in `lib/src/features/tasks/`:
|
|
- `Future<List<TaskModel>> getTasksByNamespace(String namespaceId)`
|
|
- `Future<List<TaskModel>> getTasksByEisenhowerQuadrant(int quadrant)`
|
|
- `Future<TaskModel> createTask({required String namespaceId, required String title, String? projectId})`
|
|
- `Future<void> updateTask(TaskModel task)`
|
|
- `Future<void> archiveTask(String taskId)`
|
|
- `Stream<List<TaskModel>> watchTasksByNamespace(String namespaceId)` — real-time updates via FRB stream
|
|
- Implement `TaskBloc` with events: `LoadTasks`, `CreateTask`, `UpdateTask`, `ArchiveTask`, `FilterByQuadrant`, `FilterByStatus`
|
|
- Implement `TaskModel` Dart class mirroring `FfiTaskData` with `copyWith`, `toJson`, `fromJson`
|
|
- Unit tests: `TaskBloc` state transitions, `TaskRepository` mock FFI calls
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.4 — Eisenhower Priority Matrix View
|
|
|
|
- [ ] **Task 3.4**: Implement the Eisenhower Priority Matrix UI view:
|
|
- Implement `EisenhowerScreen` with four-quadrant grid layout using Flutter `CustomPainter` or `GridView`
|
|
- Quadrant labels: Q1 "Do First" (red), Q2 "Schedule" (blue), Q3 "Delegate" (yellow), Q4 "Eliminate" (grey)
|
|
- Each quadrant renders a scrollable list of `TaskCard` widgets filtered by `eisenhower_quadrant`
|
|
- `TaskCard` widget: title, due date chip, priority score badge, status indicator, tap-to-edit
|
|
- Drag-and-drop between quadrants updates `eisenhower_quadrant` via `TaskBloc`
|
|
- Real-time score recalculation indicator (spinner when Rust engine is computing scores)
|
|
- Implement `EisenhowerBloc` with auto-refresh on task mutations
|
|
- Widget tests: quadrant rendering, task card display, drag-and-drop state update
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.5 — Calendar Time-Blocking Grid View
|
|
|
|
- [ ] **Task 3.5**: Implement the Calendar Time-Blocking Grid UI view:
|
|
- Implement `CalendarScreen` with day/week/month view toggle
|
|
- Day and week views render hourly time slots as a vertical grid using `CustomPainter`
|
|
- Unscheduled tasks panel on the left sidebar — drag tasks onto time slots to schedule them
|
|
- Dragging a task onto a slot: sets `due_date` to slot start time, sets `estimated_duration` to slot height in minutes
|
|
- Scheduled task blocks render with color-coded namespace indicators
|
|
- Implement `CalendarBloc` with events: `LoadCalendarRange`, `ScheduleTask`, `RescheduleTask`, `UnscheduleTask`
|
|
- CalDAV feed overlay: display external calendar events from local CalDAV bridge (read-only overlay)
|
|
- Widget tests: time slot rendering, drag-and-drop scheduling, duration resize handle
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.6 — Kanban Board View
|
|
|
|
- [ ] **Task 3.6**: Implement the Kanban Board UI view:
|
|
- Implement `KanbanScreen` with four status columns: Backlog, In Progress, Review, Done
|
|
- Horizontal swimlanes group tasks by `namespace_id` or `project_id` (toggle)
|
|
- `KanbanCard` widget: title, priority badge, due date, assignee avatar placeholder, tag chips
|
|
- Drag-and-drop between columns updates `status` field via `TaskBloc` and emits CRDT mutation
|
|
- Column header shows task count and WIP limit indicator (configurable)
|
|
- Implement `KanbanBloc` with events: `LoadKanban`, `MoveCard`, `FilterByNamespace`, `FilterByProject`
|
|
- Widget tests: column rendering, card drag-and-drop, status update
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.7 — Gantt Timeline View
|
|
|
|
- [ ] **Task 3.7**: Implement the interactive Gantt Timeline UI view:
|
|
- Implement `GanttScreen` with horizontal timeline using `CustomPainter`
|
|
- Renders project milestones, task bars, and sub-task nesting with fractional index ordering
|
|
- Task bars are draggable (reschedule) and resizable (change duration)
|
|
- Critical path highlighting: tasks with no slack time rendered in red
|
|
- Zoom controls: day/week/month/quarter granularity
|
|
- Implement `GanttBloc` with events: `LoadGantt`, `RescheduleTask`, `ResizeTask`, `ExpandProject`, `CollapseProject`
|
|
- Widget tests: timeline rendering, task bar positioning, zoom level changes
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.8 — Notes & Knowledge Workspace View
|
|
|
|
- [ ] **Task 3.8**: Implement the Notes & Knowledge Workspace UI view:
|
|
- Implement `NotesScreen` with left sidebar (project tree) and right editor panel
|
|
- Project tree: hierarchical `TreeView` widget rendering `projects` and `namespaces` with expand/collapse
|
|
- Markdown editor: rich text editing with live preview toggle, using `flutter_markdown` package
|
|
- Bidirectional task linking: `[[task:uuid]]` syntax renders as tappable task chips
|
|
- Daily Jots view: chronological list of unstructured notes with auto-date grouping
|
|
- Implement `NotesBloc` with events: `LoadNotes`, `CreateNote`, `UpdateNote`, `DeleteNote`, `LinkTask`, `UnlinkTask`
|
|
- Add `flutter_markdown: ^0.7.0` to `pubspec.yaml`
|
|
- Widget tests: tree view rendering, markdown preview, task link chips
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.9 — Navigation Shell & Settings
|
|
|
|
- [ ] **Task 3.9**: Implement the main navigation shell and settings screen:
|
|
- Implement `AppShell` with `NavigationRail` (desktop) / `BottomNavigationBar` (mobile) for view switching
|
|
- Navigation destinations: Eisenhower Matrix, Calendar, Kanban, Gantt, Notes, Settings
|
|
- Implement `SettingsScreen`:
|
|
- Namespace management (create, rename, color, delete)
|
|
- IMAP account configuration (host, port, username, password — stored via keychain FFI)
|
|
- P2P sync status panel: connected peers list, last sync time, manual sync trigger
|
|
- Eisenhower weight configuration (W_i, W_u, W_a sliders)
|
|
- Theme toggle (light/dark/system)
|
|
- Implement `SyncStatusWidget` — persistent bottom bar showing P2P connection state and last sync time
|
|
- Widget tests: navigation rail rendering, settings form validation
|
|
- Run `flutter test`
|
|
|
|
---
|
|
|
|
## Task 3.10 — Build Scripts & Platform Configuration
|
|
|
|
- [ ] **Task 3.10**: Create build scripts and configure platform targets:
|
|
- Create `scripts/build_desktop_libs.ps1` (Windows):
|
|
- `cargo build --release --package chronogrid_ffi`
|
|
- Copy `.dll` to `apps/chronogrid_flutter/windows/`
|
|
- Run `flutter_rust_bridge_codegen generate`
|
|
- `flutter build windows`
|
|
- Create `scripts/build_desktop_libs.sh` (Linux):
|
|
- `cargo build --release --package chronogrid_ffi --target x86_64-unknown-linux-gnu`
|
|
- Copy `.so` to `apps/chronogrid_flutter/linux/`
|
|
- `flutter build linux`
|
|
- Create `scripts/build_android_libs.sh`:
|
|
- Install Android NDK targets: `rustup target add aarch64-linux-android armv7-linux-androideabi`
|
|
- `cargo build --release --package chronogrid_ffi --target aarch64-linux-android`
|
|
- Copy `.so` to `apps/chronogrid_flutter/android/app/src/main/jniLibs/arm64-v8a/`
|
|
- `flutter build apk --release`
|
|
- Configure `apps/chronogrid_flutter/windows/CMakeLists.txt` to link `chronogrid_ffi.dll`
|
|
- Configure `apps/chronogrid_flutter/linux/CMakeLists.txt` to link `libchronogrid_ffi.so`
|
|
- Verify `flutter build windows` succeeds on Windows host
|
|
- Update `scripts/verify_agent_work.ps1` to include FRB codegen check and Windows build check
|
|
|
|
---
|
|
|
|
## Phase 3 Completion Criteria
|
|
|
|
- [ ] All 10 tasks above marked `[x]`
|
|
- [ ] `flutter test` passes with zero failures across all feature BLoCs and widgets
|
|
- [ ] `flutter build windows` produces a runnable `.exe`
|
|
- [ ] FRB codegen output exists in `apps/chronogrid_flutter/lib/src/rust/`
|
|
- [ ] All four primary views (Eisenhower, Calendar, Kanban, Notes) render from live CRDT data
|
|
- [ ] `scripts/verify_agent_work.ps1` exits with code 0
|
|
- [ ] ADR created for Flutter architecture decisions (`docs/ARCHITECTURE/ADR/0007-flutter-bloc-architecture.md`)
|
|
- [ ] `DECISION_LOG.md` updated with Phase 3 decisions
|