ai-code-app/docs/chat-frontend-rewrite-plan.md

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

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