halobestie-clone/requirement/phase3.1.md

PRD: Phase 3 Stabilization & State Management Migration

Overview

Goal: Stabilize Phase 3 (Chat Engine) through end-to-end testing and migrate Flutter state management from BLoC to Riverpod + flutter_hooks

Success looks like: All Phase 3 features are verified working end-to-end across client_app, mitra_app, and control_center. Both Flutter apps use Riverpod as their sole state management solution.

Background

• Phase 3 (Chat Engine) is fully scaffolded but has not been end-to-end tested
• Current Flutter apps use BLoC pattern; Riverpod is preferred for maintainability and reduced boilerplate
• Migration should happen before Phase 4 to avoid compounding tech debt

FCM fallback for Chat Engine

Mitra Pairing

• Add configuration on Control center to configure Mitra's app require to ping or not.
• When Control Center allow non ping, application or backend will not force mitra to ping and allow them to keep online even when the app is closed or in backround
• Modify Mitra Pairing confirmation to send notification through FCM when websocket to Mitra is closed

Bi-Directional Chat (WebSocket + FCM)

Mitra App

• When there is new unread message, mitra app must shows badge on active session
• When there is new unread message, mitra app must shows badge on the chat active session inside active session page
• Unread badge on each active session will be cleared when the message has been read
• Unread badge on active session button on main page will be cleared when the message has been read

Customer App

• When there is new unread message, Customer app must shows badge on active session
• Unread badge will be cleared when unread message has been cleared

Chat Closure & Extension

• When chat closure called, backend will send closure signal to both Mitra and Customer
• Backend will use FCM if the websocket connection is down

Control Center

• Control center shows configuration for ping from mitra

Riverpod Migration

Scope

• Migrate all BLoC classes in client_app and mitra_app to Riverpod annotation-based providers
• Replace flutter_bloc with flutter_riverpod, riverpod_annotation, flutter_hooks, and hooks_riverpod
• Add riverpod_generator + build_runner as dev dependencies for code generation
• No backend or control_center changes

Migration Strategy

• Add Riverpod dependencies (flutter_riverpod, hooks_riverpod, riverpod_annotation) and dev dependencies (riverpod_generator, build_runner, custom_lint, riverpod_lint)
• Wrap app root with ProviderScope
• Migrate one Bloc at a time, starting with the simplest (e.g. AuthBloc)
• For each migrated Bloc:
  1. Replace Bloc/Cubit class with @riverpod annotated Notifier or AsyncNotifier (extending _$ClassName)
  2. Replace BlocEvent + emit() pattern with notifier methods that update state directly
  3. Run dart run build_runner build to generate .g.dart files
  4. Replace BlocProvider with generated provider (e.g. authProvider)
  5. Replace BlocBuilder widgets with ConsumerWidget + ref.watch()
  6. Replace BlocListener with ref.listen() inside widget or provider
  7. Use HookConsumerWidget where flutter_hooks are needed (e.g. useTextEditingController, useEffect)
• Run E2E verification after each migration to catch regressions
• Remove flutter_bloc dependency only after all Blocs are migrated

Affected Blocs

• client_app — AuthBloc, PairingBloc, ChatBloc, ChatOpeningBloc, SessionClosureBloc
• mitra_app — AuthBloc, OnlineStatusBloc, MitraChatBloc, ExtensionBloc

Non-Functional Requirement

• WebSocket reconnects gracefully after network interruption (within 5s on stable network)
• Use FCM to send command or message when websocket is down
• No message loss during brief disconnects — undelivered messages sync on reconnect
• Chat screen maintains scroll position and input draft on app lifecycle events (background/foreground)
• Riverpod migration introduces zero new UI bugs — feature parity with BLoC implementation

Tech Stack

• State management: Riverpod + flutter_hooks (replacing flutter_bloc)
• No backend changes expected — migration is Flutter-only