mtkell
/
chronogrid
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
chronogrid/docs/TASKS/phase_3_flutter_ui_shell.md

12 KiB
Raw Blame History

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