# 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