# 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 initialize()` — derives master key via FFI, opens database, starts P2P swarm - `Future 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> getTasksByNamespace(String namespaceId)` - `Future> getTasksByEisenhowerQuadrant(int quadrant)` - `Future createTask({required String namespaceId, required String title, String? projectId})` - `Future updateTask(TaskModel task)` - `Future archiveTask(String taskId)` - `Stream> 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