halobestie-clone/requirement/phase3-plan.md

Phase 3 Implementation Plan: Chat Engine

Summary of Clarified Requirements

Topic	Decision
Chat opening	Time/price selection dialog before pairing
Price tiers (mock)	15min/30k, 30min/60k, 45min/100k, 60min/150k, 24jam/250k
Free trial	One-time per customer; enabled/disabled globally via Control Center
Free trial duration	Single global config value (minutes) in Control Center
Payment timing	After pairing starts, but mocked in this phase
Chat transport	WebSocket (real-time) + FCM (background push notifications)
Message types	Text-only now; schema supports image/voice/video later
Emoji	Works natively (unicode text), no special handling needed
Message status	Sent (server ack), Delivered (client ack), Read (client opened)
Typing indicator	3-second timeout, throttled (send at most once per 2-3s)
Chat history storage	Backend API as source of truth; no local cache
Session timer	Backend-authoritative (server-side countdown)
Timer warning	Show remaining time at 1 minute left
Extension timeout	1 minute for customer to decide + mitra to confirm (configurable)
Chat during extension	Paused — no messages until extension confirmed or rejected
Early end	Mechanism built, disabled by default, configurable per role
Closing message	Free-text goodbye message from both parties
Chat history view	Full read-only transcript, kept forever
Deletion requests	Deferred to later phase
Sessions per customer	One active session at a time
WSS termination	Cloud Run handles TLS; backend uses plain ws://
Control center transcripts	Viewable by certain roles only (deferred to later phase)
Notification permission	Request on first app launch

---

1. Database Changes

1.1 New table: chat_messages

Stores all chat messages.

Column	Type	Notes
id	SERIAL PRIMARY KEY
session_id	INT REFERENCES chat_sessions(id)
sender_type	VARCHAR	'customer' or 'mitra'
sender_id	INT	customer or mitra ID
type	VARCHAR DEFAULT 'text'	'text' now; 'image', 'voice', 'video' later
content	TEXT	Message text (or file URL for future media)
metadata	JSONB	Nullable; for future media (file size, duration, thumbnail)
status	VARCHAR DEFAULT 'sent'	'sent', 'delivered', 'read'
delivered_at	TIMESTAMPTZ	When recipient's client acknowledged
read_at	TIMESTAMPTZ	When recipient opened/read the message
created_at	TIMESTAMPTZ DEFAULT now()

Indexes:

• (session_id, created_at) — fetch messages in chronological order
• (session_id, status) — query undelivered/unread messages

1.2 New table: session_closures

Stores goodbye messages when a session ends.

Column	Type	Notes
id	SERIAL PRIMARY KEY
session_id	INT REFERENCES chat_sessions(id)
user_type	VARCHAR	'customer' or 'mitra'
user_id	INT	customer or mitra ID
message	TEXT	Free-text goodbye message
created_at	TIMESTAMPTZ DEFAULT now()

1.3 New table: session_extensions

Tracks extension requests and their outcomes.

Column	Type	Notes
id	SERIAL PRIMARY KEY
session_id	INT REFERENCES chat_sessions(id)
requested_duration_minutes	INT	Duration customer selected
requested_price	INT	Mock price (in IDR)
status	VARCHAR	'pending', 'accepted', 'rejected', 'timeout'
requested_at	TIMESTAMPTZ DEFAULT now()
responded_at	TIMESTAMPTZ

1.4 Alter table: chat_sessions

Add columns to support timed sessions:

Column	Type	Notes
duration_minutes	INT	Selected duration (15/30/45/60/1440)
price	INT	Mock price in IDR (0 for free trial)
is_free_trial	BOOLEAN DEFAULT false
expires_at	TIMESTAMPTZ	Computed: paired_at + duration_minutes
extended_minutes	INT DEFAULT 0	Total extended time

Add new session statuses:

• extending — customer requested extension, waiting for mitra confirmation
• closing — session ended, waiting for goodbye messages

1.5 New table: customer_transactions

Tracks whether a customer has had any transaction (for free trial eligibility).

Column	Type	Notes
id	SERIAL PRIMARY KEY
customer_id	INT REFERENCES customers(id)
session_id	INT REFERENCES chat_sessions(id)
type	VARCHAR	'free_trial', 'paid', 'extension'
amount	INT	0 for free trial
created_at	TIMESTAMPTZ DEFAULT now()

1.6 Extend app_config

New config keys:

Key	Value (JSONB)	Purpose
free_trial_enabled	{ "value": true }	Enable/disable free trial globally
free_trial_duration_minutes	{ "value": 5 }	Free trial session duration
extension_timeout_seconds	{ "value": 60 }	Time limit for extension negotiation
early_end_mitra_enabled	{ "value": false }	Allow mitra to end session early
early_end_customer_enabled	{ "value": false }	Allow customer to end session early

---

2. Backend Changes

2.1 WebSocket Setup

• Add @fastify/websocket plugin (src/plugins/websocket.js)
• Single WebSocket endpoint: GET /api/shared/ws
• Connection authenticated via Firebase token (sent as query param or first message)
• After auth, server identifies user as customer or mitra and joins them to their session channel
• Valkey pub/sub remains the backend message bus; WebSocket is the client-facing transport
• Architecture: Client ↔ WebSocket ↔ Backend ↔ Valkey pub/sub ↔ Backend ↔ WebSocket ↔ Other client

WebSocket message types (JSON):

Type	Direction	Purpose
auth	Client → Server	Authenticate with Firebase token
auth_ok	Server → Client	Authentication successful
message	Client → Server	Send a chat message
message	Server → Client	Receive a chat message
message_status	Server → Client	Delivery/read status update
message_ack	Server → Client	Server acknowledges sent message (sent status)
typing	Client → Server	User is typing
typing	Server → Client	Other user is typing
session_timer	Server → Client	Timer warning (1 min left)
session_expired	Server → Client	Session time is up
extension_request	Server → Client	Extension request notification (to mitra)
extension_response	Server → Client	Extension accepted/rejected (to customer)
session_paused	Server → Client	Chat paused during extension negotiation
session_resumed	Server → Client	Chat resumed after extension accepted
session_closing	Server → Client	Session ending, prompt for goodbye message
early_end	Client → Server	Request to end session early
delivered	Client → Server	Client acknowledges message delivery
read	Client → Server	Client marks messages as read

2.2 FCM Push Notification Setup

• Use existing firebase-admin plugin for sending push notifications
• Store FCM device token per user (new columns on customers and mitras tables)
• Send push notification when recipient's WebSocket is not connected
• FCM payload includes: message preview, session ID, sender name
• On notification tap: deep-link to specific chat screen

New columns:

Table	Column	Type
customers	fcm_token	VARCHAR
mitras	fcm_token	VARCHAR

New endpoint:

Method	Path	Purpose
POST	/api/shared/device-token	Register/update FCM device token

2.3 New Public Routes — Chat Opening

Method	Path	Purpose
GET	/api/client/chat/pricing	Get mock price tiers + free trial eligibility
POST	/api/client/chat/request	Start pairing with selected duration/price (updated from Phase 2)

2.4 New Public Routes — Chat Messages

Method	Path	Purpose
GET	/api/shared/chat/:sessionId/messages	Fetch message history (paginated, for reconnect)
GET	/api/shared/chat/:sessionId/info	Get session info (timer, status, participants)

2.5 New Public Routes — Session Closure

Method	Path	Purpose
POST	/api/client/sessions/:sessionId/extend	Customer requests extension with selected duration
POST	/api/mitra/sessions/:sessionId/extend-response	Mitra accepts/rejects extension
POST	/api/shared/sessions/:sessionId/close-message	Submit goodbye message

2.6 New Public Routes — Chat History

Method	Path	Purpose
GET	/api/client/chat/history	List past sessions (with mitra name, closure messages)
GET	/api/mitra/chat/history	List past sessions (with customer name, closure messages)
GET	/api/shared/chat/:sessionId/transcript	Full read-only chat transcript

2.7 New Internal Routes — Control Center

Method	Path	Purpose
GET	/internal/config/free-trial	Get free trial config
PATCH	/internal/config/free-trial	Update free trial enabled + duration
GET	/internal/config/extension-timeout	Get extension timeout config
PATCH	/internal/config/extension-timeout	Update extension timeout
GET	/internal/config/early-end	Get early end config
PATCH	/internal/config/early-end	Update early end per role

2.8 New Services

Service	Responsibilities
chat.service.js	Send message, update delivery/read status, fetch message history, typing event relay
session-timer.service.js	Backend-authoritative countdown, expiry check, 1-min warning trigger, extension timeout
extension.service.js	Extension request/response flow, session pause/resume, timeout handling
closure.service.js	Goodbye message submission, session completion, transaction recording
notification.service.js	FCM push notification sending, device token management, online/offline detection
pricing.service.js	Mock price tiers, free trial eligibility check

2.9 Chat Flow (Backend Detail)

Chat Opening:
1. Customer opens "Mulai Curhat"
2. Backend returns pricing tiers + free trial eligibility
   - Free trial shown if: free_trial_enabled AND customer has 0 records in customer_transactions
3. Customer selects duration/price (or free trial)
4. POST /api/client/chat/request with { duration_minutes, price, is_free_trial }
5. Backend creates chat_session with duration_minutes, price, is_free_trial
6. Existing Phase 2 pairing flow proceeds (blast, accept, etc.)
7. On successful pairing:
   - Set expires_at = now() + duration_minutes
   - Create customer_transactions record
   - Start server-side timer

Chat Messaging:
1. Both parties connect via WebSocket after pairing
2. Client sends { type: 'message', content: '...' }
3. Backend saves to chat_messages (status: 'sent'), publishes via Valkey
4. Backend sends message_ack to sender (sent ✓)
5. Recipient's WebSocket receives message
6. Recipient sends { type: 'delivered' } → backend updates status, notifies sender (delivered ✓✓)
7. Recipient views message → sends { type: 'read' } → backend updates status (read ✓✓ blue)
8. If recipient offline → backend sends FCM push notification instead

Session Expiry:
1. Backend timer fires 1 min before expires_at
2. Send session_timer to both clients via WebSocket
3. Both apps show countdown timer
4. At expires_at, backend sends session_expired
5. Customer gets extend/close dialog
6. If extend: POST /api/client/sessions/:id/extend
   - Session status → extending, chat paused
   - Mitra gets extension_request via WebSocket
   - Mitra accepts/rejects within timeout (default 60s)
   - If accept: extend expires_at, resume chat
   - If reject or timeout: proceed to closure
7. If close (or after rejected extension):
   - Session status → closing
   - Both parties submit goodbye message
   - Session status → completed

Early End (when enabled):
1. User sends { type: 'early_end' } via WebSocket
2. Backend checks if early end is enabled for that role
3. If enabled: skip to closure flow (step 7 above)
4. If disabled: reject with error

2.10 Typing Indicator (Backend Detail)

1. Client sends { type: 'typing' } via WebSocket
2. Backend relays to other party via Valkey pub/sub → WebSocket
3. Receiving client shows typing indicator
4. Receiving client auto-hides after 3 seconds of no new typing event
5. Sending client throttles: at most one typing event per 2 seconds

---

3. Client App Changes

3.1 New BLoC: ChatBloc

Manages active chat messaging.

Events: ConnectWebSocket, DisconnectWebSocket, SendMessage, MessageReceived, MessageStatusUpdate, TypingStarted, TypingStopped, SessionTimerWarning, SessionExpired States: ChatInitial, ChatConnecting, ChatConnected(messages), ChatTimerWarning(remaining), ChatSessionExpired, ChatError

• On ConnectWebSocket → authenticate, load message history from API, listen for incoming messages
• On SendMessage → send via WebSocket, add to local message list with "sending" state
• On MessageReceived → add to list, send delivery acknowledgment
• On MessageStatusUpdate → update message status (sent → delivered → read)

3.2 New BLoC: ChatOpeningBloc

Manages pricing selection and free trial.

Events: LoadPricing, SelectTier, SelectFreeTrial, ConfirmSelection States: PricingLoading, PricingLoaded(tiers, freeTrialEligible), TierSelected(tier), PricingError

• On LoadPricing → call /api/client/chat/pricing
• On ConfirmSelection → trigger existing PairingBloc.RequestPairing with duration/price

3.3 New BLoC: SessionClosureBloc

Manages extension and goodbye flow.

Events: SessionExpired, RequestExtension, ExtensionResult, SubmitGoodbye States: ClosureInitial, ShowExtendDialog, ExtendingWaitingMitra, ExtensionAccepted, ExtensionRejected, ShowGoodbyeInput, ClosureComplete

3.4 Screen Changes

Screen	Changes
Home screen	"Mulai Curhat" opens pricing dialog instead of directly pairing
New: Pricing dialog	Bottom sheet with 5 price tiers + free trial option (if eligible)
New: Chat screen	Full chat UI: message list, text input, send button, typing indicator
Chat screen	Message bubbles with status icons (✓ sent, ✓✓ delivered, ✓✓ blue read)
Chat screen	Countdown timer overlay at 1 minute remaining
New: Extension dialog	"Extend session?" with price tier selection
New: Waiting mitra dialog	"Menunggu konfirmasi Bestie..." with timeout
New: Goodbye screen	Free-text input for closing message
New: Chat history list	List of past sessions (bestie name, date, goodbye message)
New: Chat transcript screen	Read-only scrollable chat history

3.5 Navigation Updates

New routes in GoRouter:

• /chat/pricing — pricing selection dialog/screen
• /chat/session/:sessionId — active chat screen (updated from Phase 2)
• /chat/history — chat history list
• /chat/history/:sessionId — read-only transcript

3.6 FCM Setup

• Request notification permission on first app launch
• Register device token via POST /api/shared/device-token
• Handle incoming notifications: tap → navigate to specific chat screen
• Update token on app launch (tokens can rotate)

---

4. Mitra App Changes

4.1 New BLoC: ChatBloc

Same as client app — manages active chat messaging. Shared message type structure.

Events/States: Same as client app ChatBloc.

4.2 New BLoC: ExtensionBloc

Handles incoming extension requests from customers.

Events: ExtensionReceived, AcceptExtension, RejectExtension, ExtensionTimeout States: ExtensionIdle, ExtensionPending(duration, price), ExtensionAccepted, ExtensionRejected

4.3 Screen Changes

Screen	Changes
Home screen	Active sessions list → tap to open chat
New: Chat screen	Full chat UI (same as client app)
Chat screen	Extension request overlay when customer requests extension
New: Extension dialog	"Customer ingin perpanjang X menit" with Accept/Reject buttons
New: Goodbye screen	Free-text input for closing message
New: Chat history list	List of past sessions (customer name, date, goodbye message)
New: Chat transcript screen	Read-only scrollable chat history

4.4 Navigation Updates

New routes in GoRouter:

• /chat/session/:sessionId — active chat screen
• /chat/history — chat history list
• /chat/history/:sessionId — read-only transcript

4.5 FCM Setup

• Same as client app: request permission on launch, register token
• Push notification on incoming message when app is backgrounded
• Tap notification → navigate directly to specific customer's chat screen (not just chat list)

---

5. Control Center Changes

5.1 Updated Pages

Page	Changes
Settings page	Add: free trial toggle + duration, extension timeout, early end toggles (mitra/customer)
Session detail page	Add: view chat transcript link (role-restricted, deferred)

5.2 No New Pages This Phase

Chat transcript viewing for admins is deferred. Config controls are added to the existing Settings page.

---

6. Implementation Order

Step	What	Apps affected
1	Database migration (new tables, altered columns, new config keys)	Backend
2	WebSocket plugin setup (@fastify/websocket)	Backend
3	Pricing service + free trial eligibility + chat opening API	Backend
4	Chat message service + WebSocket message handling	Backend
5	Message delivery/read status tracking	Backend
6	Session timer service (backend-authoritative countdown)	Backend
7	Extension service (request/response/timeout)	Backend
8	Closure service (goodbye messages, session completion)	Backend
9	FCM notification service + device token endpoint	Backend
10	Client app: FCM setup + pricing dialog + ChatOpeningBloc	Client app
11	Client app: ChatBloc + chat screen + message status UI	Client app
12	Client app: timer warning + extension dialog + SessionClosureBloc	Client app
13	Client app: goodbye screen + chat history screens	Client app
14	Mitra app: FCM setup + ChatBloc + chat screen	Mitra app
15	Mitra app: ExtensionBloc + extension dialog	Mitra app
16	Mitra app: goodbye screen + chat history screens	Mitra app
17	Control center: settings page updates (free trial, extension, early end)	Control center
18	Typing indicator (WebSocket relay, throttle, 3s timeout)	Backend + both apps

---

7. New Dependencies

App	Package	Purpose
Backend	@fastify/websocket	WebSocket support (built on ws)
Backend	firebase-admin (existing)	FCM push notifications
Client app	web_socket_channel	WebSocket client
Client app	firebase_messaging	FCM push notifications
Mitra app	web_socket_channel	WebSocket client
Mitra app	firebase_messaging	FCM push notifications

---

8. Notes for Future Phases

Media messages (image, voice clip, video clip):

• Add file upload endpoint (Cloud Storage)
• Add new type values to chat_messages
• Add media bubble widgets in Flutter
• No architectural changes — same WebSocket transport, same delivery status, same history

Chat transcript for Control Center:

• Add role-based access check
• Reuse existing /api/shared/chat/:sessionId/transcript endpoint on internal routes

Deletion requests:

• Add customer request flow + admin approval
• Soft-delete or anonymize messages in chat_messages

Payment integration (Xendit):

• Replace mock pricing with real payment flow
• Integrate at the pending_payment status transition point
• Extension payments follow same flow