Add persistent AI connection indicator and WebSocket heartbeat

- Add persistent connection status badge in header (green/red indicator)
- Implement WebSocket ping/pong heartbeat (30s interval) to prevent idle disconnections
- Handle heartbeat messages in backend gateway with pong responses
- Configure nginx WebSocket timeouts (5 minutes as safety net)
- Enhance CLAUDE.md with debugging commands, MCP tools list, and architecture details

Fixes constant reconnection issues caused by proxy timeout on idle connections.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: anatoly314

CLAUDE.md

@@ -45,6 +45,16 @@ pnpm clean          # Clean all build artifacts and node_modules
 pnpm backend:inspector  # Launch MCP Inspector for testing tools (STDIO mode)
 ```
 
+**Backend-specific commands** (when working in apps/backend):
+
+```bash
+npm run inspector:stdio        # Run MCP inspector for STDIO mode
+npm run inspector:stdio:debug  # Run STDIO inspector with debugger on port 9229
+npm run inspector:http         # Run MCP inspector for HTTP mode
+npm run start:debug:stdio      # STDIO mode with debugger
+npm run start:debug:http       # HTTP mode with debugger
+```
+
 ### Docker
 
 **Run from GHCR:**
@@ -128,9 +138,13 @@ This is a **pnpm workspaces + Turborepo** monorepo (converted from standalone ap
 - Frontend connects to backend via WebSocket at `/remote-control`
 - Enabled when `VITE_REMOTE_CONTROL_ENABLED=true` (automatically set in Docker builds)
 - WebSocket auto-detects URL from browser (supports both direct access and nginx proxy)
-- Commands are handled by contexts, responses sent back to backend
-- Automatic reconnection with exponential backoff (max 10 attempts, up to 30s delay)
-- Connection status displayed via Toast notifications
+  - Auto-detection: `ws://localhost:5173/remote-control` (dev) or `ws://localhost:8080/remote-control` (Docker)
+  - Protocol switches to `wss://` for HTTPS connections
+- Commands are handled by contexts (`DiagramContext`, `AreasContext`, `NotesContext`, etc.)
+- Automatic reconnection with exponential backoff (max 10 attempts, up to 30s delay with jitter)
+- Connection status displayed via Toast notifications ("AI Assistant connected/disconnected")
+- All commands processed through `useRemoteControl.js:152` switch statement
+- Command timeout: 30 seconds (configured in `DrawDBClientService:15`)
 
 ### Backend (apps/backend)
 
@@ -217,17 +231,18 @@ Example: `apps/backend/src/mcp/primitives/essential/tools/add-table.tool.ts`
 
 **Available Commands:**
 
-- `getDiagram()` - Get full diagram state
+- `getDiagram()` - Get full diagram state (all entities)
 - `addTable()`, `updateTable()`, `deleteTable()` - Table operations
 - `addField()`, `updateField()`, `deleteField()` - Field operations
 - `addRelationship()`, `updateRelationship()`, `deleteRelationship()` - Relationship operations
 - `addArea()`, `updateArea()`, `deleteArea()` - Area (grouping) operations
 - `addNote()`, `updateNote()`, `deleteNote()` - Note operations
 - `addEnum()`, `updateEnum()`, `deleteEnum()` - PostgreSQL ENUM type operations
 - `addType()`, `updateType()`, `deleteType()` - PostgreSQL composite type operations
-- `getTables()`, `getTable()`, `getRelationships()`, `getAreas()`, `getNotes()`, `getEnums()`, `getTypes()` - Query operations
-- `setDatabase()` - Set database type (MySQL, PostgreSQL, SQLite, etc.)
-- `importDiagram()` - Import complete diagram JSON
+- `getTables()`, `getTable()`, `getRelationships()`, `getAreas()`, `getNotes()`, `getEnums()`, `getTypes()` - Query operations (read-only)
+- `setDatabase()` - Set database type (MySQL, PostgreSQL, SQLite, MSSQL, MariaDB)
+- `importDiagram()` - Import complete diagram JSON (replaces current diagram)
+- `exportDiagram()` - Export diagram to SQL, JSON, or other formats (available via MCP tool)
 
 See `apps/backend/src/drawdb/drawdb-client.service.ts` and `apps/gui/src/hooks/useRemoteControl.js` for full command list.
 
@@ -292,6 +307,51 @@ node dist/main-http.js --port 3000 --host 127.0.0.1
 
 ## Development Tips
 
+### Available MCP Tools
+
+The backend exposes the following MCP tools (located in `apps/backend/src/mcp/primitives/essential/tools/`):
+
+**Table Tools:**
+- `add-table` - Create new table with fields
+- `update-table` - Modify table properties (name, color, position, comment)
+- `delete-table` - Remove table from diagram
+- `get-table` - Retrieve single table by ID or name
+
+**Field Tools:**
+- `add-field` - Add field to existing table
+- `update-field` - Modify field properties (type, constraints, etc.)
+- `delete-field` - Remove field from table
+
+**Relationship Tools:**
+- `add-relationship` - Create relationship between tables
+- `update-relationship` - Modify relationship properties
+- `delete-relationship` - Remove relationship
+
+**Area Tools:**
+- `add-area` - Create grouping area for tables
+- `update-area` - Modify area properties (name, size, color, position)
+- `delete-area` - Remove area
+
+**Note Tools:**
+- `add-note` - Create text note with Lexical editor content
+- `update-note` - Modify note content or properties
+- `delete-note` - Remove note
+
+**PostgreSQL Type Tools:**
+- `add-enum` - Create ENUM type with values
+- `update-enum` - Modify ENUM values
+- `delete-enum` - Remove ENUM type
+- `add-type` - Create composite type with fields
+- `update-type` - Modify composite type
+- `delete-type` - Remove composite type
+
+**Diagram Tools:**
+- `get-diagram` - Retrieve entire diagram state (all entities)
+- `import-diagram` - Replace diagram with JSON data
+- `export-diagram` - Export to SQL, JSON, or other formats
+
+Each tool validates input using Zod schemas and communicates with the frontend via WebSocket.
+
 ### Adding a New MCP Tool
 
 1. Create `apps/backend/src/mcp/primitives/essential/tools/your-tool.tool.ts`
@@ -305,7 +365,13 @@ node dist/main-http.js --port 3000 --host 127.0.0.1
 1. Start backend: `pnpm backend:dev`
 2. Start frontend: `pnpm gui:dev`
 3. Open browser console, check for "DrawDB client connected" in backend logs
-4. Use MCP Inspector to test tools: `pnpm backend:inspector` (requires separate STDIO mode)
+4. Use MCP Inspector to test tools: `pnpm backend:inspector` (STDIO mode)
+
+**For debugging with breakpoints:**
+
+1. Run `npm run inspector:stdio:debug` in `apps/backend` directory
+2. Attach your IDE debugger to port 9229
+3. Inspector pauses at startup waiting for debugger attachment
 
 ### Debugging Docker Build
 
@@ -335,12 +401,14 @@ function MyComponent() {
 ### Common Gotchas
 
 - **WebSocket connection fails**: Check that `VITE_REMOTE_CONTROL_ENABLED=true` and backend is running
-- **MCP tools timeout**: Default timeout is 30s (configured in `DrawDBClientService:16`)
+- **MCP tools timeout**: Default timeout is 30s (configured in `DrawDBClientService:15`)
 - **Docker nginx issues**: Nginx runs as non-root user `nodejs:nodejs`, requires proper permissions
 - **Build failures**: Run `pnpm clean` then `pnpm install` to reset
 - **Turborepo cache issues**: Delete `.turbo` directory to clear cache
-- **Area/Note deletion**: Areas and notes use numeric array indices internally but are looked up by `name`/`title` for MCP operations
-- **Field IDs**: All entities (tables, fields, relationships) use `nanoid()` for ID generation
+- **Area/Note lookup**: Areas and notes use numeric IDs internally but MCP tools look them up by `name`/`title`. When deleting, the ID is converted to integer for array lookup (`parseInt(params.id, 10)`)
+- **Entity IDs**: All entities (tables, fields, relationships, enums, types) use `nanoid()` for unique ID generation (imported from `nanoid` package)
+- **Remote control enabled check**: Frontend checks `import.meta.env.VITE_REMOTE_CONTROL_ENABLED` to enable WebSocket connection (see `useRemoteControl.js:34`)
+- **Command ID format**: Backend generates unique command IDs using `cmd_${timestamp}_${random}` pattern for request/response matching
 
 ## CI/CD and Deployment
 
@@ -363,9 +431,9 @@ function MyComponent() {
 
 ### Version Management
 
-- Backend version: `apps/backend/package.json` (currently 1.1.2)
+- Backend version: `apps/backend/package.json` (currently 1.1.4)
 - GUI version: `apps/gui/package.json` (currently 1.0.0)
-- Root package: `package.json` (workspace root)
+- Root package: `package.json` (workspace root, 1.0.0)
 
 ## Git Workflow
 

apps/backend/src/drawdb/drawdb-client.service.ts

@@ -24,7 +24,17 @@ export class DrawDBClientService {
     // Setup message handler
     ws.on('message', (data: string) => {
       try {
-        const response: DrawDBResponse = JSON.parse(data);
+        const message = JSON.parse(data);
+
+        // Handle ping/pong heartbeat
+        if (message.type === 'ping') {
+          this.logger.debug('Received ping, sending pong');
+          ws.send(JSON.stringify({ type: 'pong' }));
+          return;
+        }
+
+        // Handle normal command responses
+        const response: DrawDBResponse = message;
         this.handleResponse(response);
       } catch (error) {
         this.logger.error('Failed to parse message from DrawDB client:', error);

apps/gui/src/components/EditorHeader/ControlPanel.jsx

@@ -92,6 +92,7 @@ export default function ControlPanel({
   title,
   setTitle,
   lastSaved,
+  aiAssistantConnected,
 }) {
   const [modal, setModal] = useState(MODAL.NONE);
   const [sidesheet, setSidesheet] = useState(SIDESHEET.NONE);
@@ -2040,6 +2041,21 @@ export default function ControlPanel({
                   {getState()}
                 </Tag>
               )}
+              {aiAssistantConnected !== null && (
+                <Tooltip content={aiAssistantConnected ? "AI Assistant connected and ready" : "AI Assistant disconnected"} position="bottom">
+                  <Tag
+                    size="small"
+                    color={aiAssistantConnected ? "green" : "red"}
+                    prefixIcon={
+                      <span style={{ fontSize: '10px' }}>
+                        {aiAssistantConnected ? '●' : '○'}
+                      </span>
+                    }
+                  >
+                    {aiAssistantConnected ? "AI Connected" : "AI Disconnected"}
+                  </Tag>
+                </Tooltip>
+              )}
             </div>
           </div>
         </div>

apps/gui/src/components/Workspace.jsx

@@ -72,7 +72,7 @@ export default function WorkSpace() {
 
   // Enable remote control if VITE_REMOTE_CONTROL_ENABLED is set
   const remoteControlEnabled = import.meta.env.VITE_REMOTE_CONTROL_ENABLED === "true";
-  useRemoteControl(remoteControlEnabled);
+  const { isConnected: aiAssistantConnected } = useRemoteControl(remoteControlEnabled);
   const handleResize = (e) => {
     if (!resize) return;
     const w = isRtl(i18n.language) ? window.innerWidth - e.clientX : e.clientX;
@@ -436,6 +436,7 @@ export default function WorkSpace() {
           setTitle={setTitle}
           lastSaved={lastSaved}
           setLastSaved={setLastSaved}
+          aiAssistantConnected={remoteControlEnabled ? aiAssistantConnected : null}
         />
       </IdContext.Provider>
       <div

apps/gui/src/hooks/useRemoteControl.js

@@ -15,6 +15,7 @@ export function useRemoteControl(enabled = false) {
   const wsRef = useRef(null);
   const reconnectTimeoutRef = useRef(null);
   const reconnectAttemptsRef = useRef(0);
+  const pingIntervalRef = useRef(null);
   const [isConnected, setIsConnected] = useState(false);
 
   const diagram = useContext(DiagramContext);
@@ -41,6 +42,10 @@ export function useRemoteControl(enabled = false) {
         clearTimeout(reconnectTimeoutRef.current);
         reconnectTimeoutRef.current = null;
       }
+      if (pingIntervalRef.current) {
+        clearInterval(pingIntervalRef.current);
+        pingIntervalRef.current = null;
+      }
       setIsConnected(false);
       return;
     }
@@ -77,11 +82,26 @@ export function useRemoteControl(enabled = false) {
         } else {
           Toast.success("AI Assistant connected");
         }
+
+        // Start heartbeat ping every 30 seconds to keep connection alive
+        pingIntervalRef.current = setInterval(() => {
+          if (wsRef.current?.readyState === WebSocket.OPEN) {
+            wsRef.current.send(JSON.stringify({ type: "ping" }));
+            console.log("[RemoteControl] Sent ping");
+          }
+        }, 30000); // 30 seconds
       };
 
       ws.onmessage = (event) => {
         try {
           const message = JSON.parse(event.data);
+
+          // Handle pong response
+          if (message.type === "pong") {
+            console.log("[RemoteControl] Received pong");
+            return;
+          }
+
           handleCommand(message);
         } catch (error) {
           console.error("[RemoteControl] Failed to parse message:", error);
@@ -98,6 +118,12 @@ export function useRemoteControl(enabled = false) {
         setIsConnected(false);
         wsRef.current = null;
 
+        // Clear ping interval
+        if (pingIntervalRef.current) {
+          clearInterval(pingIntervalRef.current);
+          pingIntervalRef.current = null;
+        }
+
         // Only attempt to reconnect if enabled and haven't exceeded max attempts
         if (enabled && reconnectAttemptsRef.current < maxReconnectAttempts) {
           reconnectAttemptsRef.current++;
@@ -139,6 +165,10 @@ export function useRemoteControl(enabled = false) {
         clearTimeout(reconnectTimeoutRef.current);
         reconnectTimeoutRef.current = null;
       }
+      if (pingIntervalRef.current) {
+        clearInterval(pingIntervalRef.current);
+        pingIntervalRef.current = null;
+      }
       setIsConnected(false);
     };
   }, [enabled]);

docker/nginx.conf

@@ -23,5 +23,10 @@ server {
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
         proxy_set_header Host $host;
+
+        # WebSocket timeout configuration
+        # Set to 5 minutes as safety net (ping interval is 30s)
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
     }
 }