250 lines
5.7 KiB
Markdown
250 lines
5.7 KiB
Markdown
# Chat Frontend Rewrite Plan
|
|
|
|
## Goal
|
|
|
|
Rebuild the chat frontend around explicit feature boundaries instead of one large panel. The rewrite keeps the current server contract for now, but removes direct API coupling from UI components and preserves the current mobile visual structure.
|
|
|
|
## Non-Goals
|
|
|
|
The first rewrite wave does not change:
|
|
|
|
1. Work server REST endpoint shapes
|
|
2. Work server WebSocket event payload shapes
|
|
3. Existing chat database schema
|
|
4. Current mobile interaction model and visual hierarchy
|
|
|
|
## Current Pain Points
|
|
|
|
The existing frontend mixes too many concerns in the same render tree:
|
|
|
|
1. Session routing and panel selection
|
|
2. Conversation list fetch and sort
|
|
3. Conversation detail recovery
|
|
4. Composer draft and upload lifecycle
|
|
5. WebSocket connection and reconnect
|
|
6. Runtime dashboard fetch and live updates
|
|
7. Error log loading
|
|
8. Notification unread sync
|
|
9. Visibility, focus, reconnect, and page restore sync
|
|
|
|
This creates three classes of failures:
|
|
|
|
1. Render loops from unstable effect dependencies
|
|
2. Request storms from duplicate fetch paths
|
|
3. Partial outages where one failing concern blanks the whole chat workspace
|
|
|
|
## Rewrite Strategy
|
|
|
|
The rewrite is frontend-first, but not frontend-only in architecture. The new frontend must assume that API latency and WebSocket reconnects can fail, and each feature controller must degrade independently.
|
|
|
|
### Guiding Rules
|
|
|
|
1. UI components do not call REST helpers directly
|
|
2. UI components do not build WebSocket URLs directly
|
|
3. One feature controller owns one feature's network lifecycle
|
|
4. Shell state never performs data fetches
|
|
5. Mobile layout is preserved while data flow is replaced under it
|
|
|
|
## Feature Inventory
|
|
|
|
### 1. Workspace Shell
|
|
|
|
Responsibilities:
|
|
|
|
1. Hold `chat | runtime | errors` selection
|
|
2. Hold active session id
|
|
3. Hold mobile split-pane visibility
|
|
4. Compose feature panes
|
|
|
|
Rules:
|
|
|
|
1. No direct REST calls
|
|
2. No direct socket usage
|
|
3. No data caching
|
|
|
|
### 2. Conversation List
|
|
|
|
Responsibilities:
|
|
|
|
1. Load room summaries
|
|
2. Search and sort locally
|
|
3. Create, rename, delete, and select rooms
|
|
4. Expose unread and processing badges
|
|
|
|
Rules:
|
|
|
|
1. One fetch source
|
|
2. One short-lived in-flight dedupe layer
|
|
3. No room detail fetch inside the list controller
|
|
|
|
### 3. Conversation Room
|
|
|
|
Responsibilities:
|
|
|
|
1. Load one room detail
|
|
2. Merge server messages with optimistic local state
|
|
3. Recover state after reconnect
|
|
4. Mark replies as read
|
|
|
|
Rules:
|
|
|
|
1. Only one active detail request at a time
|
|
2. Detail loading must never fan out into list reloads
|
|
3. Loading and recovery state must be local to the active room
|
|
|
|
### 4. Composer
|
|
|
|
Responsibilities:
|
|
|
|
1. Hold draft and attachments
|
|
2. Submit queue or direct requests
|
|
3. Retry, cancel, and delete pending items
|
|
4. Manage optimistic user/request messages
|
|
|
|
Rules:
|
|
|
|
1. No list-wide refresh on send
|
|
2. No runtime refresh coupled to draft input
|
|
|
|
### 5. Live Connection
|
|
|
|
Responsibilities:
|
|
|
|
1. Open and maintain the shared chat socket
|
|
2. Route message, job, runtime, and activity events
|
|
3. Reconnect with bounded recovery
|
|
4. Publish connection state through a shared adapter
|
|
|
|
Rules:
|
|
|
|
1. No duplicate context writes
|
|
2. Background transitions are throttled
|
|
3. Reconnect only restores the active room by default
|
|
|
|
### 6. Runtime
|
|
|
|
Responsibilities:
|
|
|
|
1. Load runtime snapshot
|
|
2. Show queue and active jobs
|
|
3. Load per-job detail
|
|
4. Support remove and cancel actions
|
|
|
|
Rules:
|
|
|
|
1. Runtime refresh is separate from room detail refresh
|
|
2. Runtime failure must not blank the chat room UI
|
|
|
|
### 7. Error Viewer
|
|
|
|
Responsibilities:
|
|
|
|
1. Load error log list
|
|
2. Render error detail and resource previews
|
|
|
|
Rules:
|
|
|
|
1. Fully isolated from chat room state
|
|
|
|
### 8. Notification Integration
|
|
|
|
Responsibilities:
|
|
|
|
1. Unread badges
|
|
2. Notification center list/detail
|
|
3. Offline room notifications
|
|
|
|
Rules:
|
|
|
|
1. No room detail polling from notification badge refresh
|
|
2. No direct dependency from notification UI to chat room rendering
|
|
|
|
## New Frontend Layers
|
|
|
|
### A. UI Layer
|
|
|
|
Files under `components/` and pane files.
|
|
|
|
Responsibilities:
|
|
|
|
1. Render props only
|
|
2. Emit user actions only
|
|
|
|
### B. Feature Controller Layer
|
|
|
|
Files under `hooks/`.
|
|
|
|
Responsibilities:
|
|
|
|
1. Manage one feature's state machine
|
|
2. Translate UI actions to gateway calls
|
|
3. Own loading and error state
|
|
|
|
### C. Gateway Layer
|
|
|
|
Files under `data/`.
|
|
|
|
Responsibilities:
|
|
|
|
1. Wrap all chat REST calls
|
|
2. Wrap all chat socket entry points
|
|
3. Normalize fallback behavior and timeouts in one place
|
|
|
|
This is the critical separation that the old frontend does not have.
|
|
|
|
## Target Folder Shape
|
|
|
|
```text
|
|
src/app/main/chatV2/
|
|
ChatWorkspaceV2.tsx
|
|
types.ts
|
|
data/
|
|
chatGateway.ts
|
|
chatConnectionGateway.ts
|
|
hooks/
|
|
useChatWorkspaceState.ts
|
|
useConversationListController.ts
|
|
useConversationRoomController.ts
|
|
useComposerController.ts
|
|
useRuntimeController.ts
|
|
useNotificationController.ts
|
|
components/
|
|
ConversationListPane.tsx
|
|
ConversationRoomPane.tsx
|
|
Composer.tsx
|
|
RuntimePane.tsx
|
|
ErrorPane.tsx
|
|
```
|
|
|
|
## Migration Waves
|
|
|
|
### Wave 1
|
|
|
|
1. Freeze mobile layout
|
|
2. Introduce chatV2 gateway layer
|
|
3. Move list/detail/runtime access behind the gateway
|
|
|
|
### Wave 2
|
|
|
|
1. Replace list controller
|
|
2. Replace room controller
|
|
3. Replace composer controller
|
|
|
|
### Wave 3
|
|
|
|
1. Reconnect runtime and notifications through new controllers
|
|
2. Remove old `MainChatPanel` effect chains
|
|
|
|
### Wave 4
|
|
|
|
1. Make `MainChatPanel` a thin compatibility wrapper or replace it entirely
|
|
|
|
## Success Criteria
|
|
|
|
1. Main load triggers one list fetch
|
|
2. Opening one room triggers one detail fetch
|
|
3. No direct browser fallback to external `:3100` ports on remote hosts
|
|
4. WebSocket and REST routing live in one gateway boundary
|
|
5. One pane can fail without blanking the others
|
|
6. Mobile layout matches the pre-rewrite visual structure
|