feat: comprehensive readiness check — wait for ALL services before UI

Loading overlay now checks /api/readiness which verifies ALL 4 services:
- Express server (always true if endpoint responds)
- WebSocket (frontRouteRegistered)
- dbservice (port 30002 /health)
- toolService (port 30004 /health)

Previously only checked WebSocket which was ready before dbservice,
causing premature UI interaction that crashed dbservice startup.

Added APIManager.checkReadiness() and updated Layout to use it.
Tests updated with mock for checkReadiness.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: amingclawdev

client/src/Layout/index.js

@@ -55,22 +55,21 @@ const Layout = ({ Child }) => {
 
   const fetchFingerPrints = useFingerPrintStore((state)=>state.fetchFingerPrints);
 
-  // Backend readiness check — block UI until backend services are up
+  // Backend readiness check — block UI until ALL backend services are up
   useEffect(() => {
     let cancelled = false;
-    const api = APIManager.getInstance();
-    const MAX_RETRIES = 30; // 30 x 1s = 30s max wait
+    const MAX_RETRIES = 60; // 60 x 1s = 60s max wait
     let attempt = 0;
     const check = async () => {
       while (!cancelled && attempt < MAX_RETRIES) {
         attempt++;
         try {
-          const res = await api.checkWebSocket();
-          if (res && res.success !== false) {
+          const res = await APIManager.getInstance().checkReadiness();
+          if (res && res.success) {
             if (!cancelled) setBackendReady(true);
             return;
           }
-        } catch (_) { /* retry */ }
+        } catch (_) { /* server not up yet */ }
         await new Promise(r => setTimeout(r, 1000));
       }
       if (!cancelled) setBackendError('Backend services failed to start. Please restart the application.');

client/src/Layout/index.test.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import '@testing-library/jest-dom';
-import { render, screen, fireEvent, act } from '@testing-library/react';
+import { render, screen, fireEvent, act, waitFor } from '@testing-library/react';
 
 jest.mock('react-i18next', () => ({
     useTranslation: () => ({
@@ -45,7 +45,8 @@ jest.mock('../utils/api', () => ({
         getInstance: () => ({
             getFingerPrintCount: jest.fn().mockResolvedValue({ success: true, message: 0 }),
             setStateLanguage: jest.fn().mockResolvedValue({ success: true }),
-            checkWebSocket: jest.fn().mockResolvedValue({ success: true })
+            checkWebSocket: jest.fn().mockResolvedValue({ success: true }),
+            checkReadiness: jest.fn().mockResolvedValue({ success: true, checks: { server: true, webSocket: true, dbservice: true, toolService: true } })
         })
     }
 }));
@@ -64,12 +65,13 @@ describe('Layout', () => {
 
     it('renders child component and sidebar', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
-        expect(screen.getByTestId('child')).toBeInTheDocument();
+        await waitFor(() => expect(screen.getByTestId('child')).toBeInTheDocument(), { timeout: 3000 });
         expect(screen.getByText('Web3ToolBox')).toBeInTheDocument();
     });
 
     it('renders all menu items', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         expect(screen.getByTitle('introduction')).toBeInTheDocument();
         expect(screen.getByTitle('chromeManage')).toBeInTheDocument();
         expect(screen.getByTitle('walletManage')).toBeInTheDocument();
@@ -79,13 +81,15 @@ describe('Layout', () => {
 
     it('toggles sidebar collapse', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         const toggleBtn = screen.getByLabelText('Collapse Navigation');
         fireEvent.click(toggleBtn);
         expect(window.localStorage.getItem('layout.sidebarCollapsed')).toBe('1');
     });
 
     it('opens task offcanvas on taskExecuted event', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         expect(screen.queryByTestId('task-offcanvas')).not.toBeInTheDocument();
         act(() => {
             eventEmitter.emit('taskExecuted');
@@ -95,12 +99,14 @@ describe('Layout', () => {
 
     it('opens task offcanvas on button click', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         fireEvent.click(screen.getByTestId('task-info-button'));
         expect(screen.getByTestId('task-offcanvas')).toBeInTheDocument();
     });
 
     it('opens and uses language offcanvas', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         fireEvent.click(screen.getByTitle('changeLang'));
         expect(screen.getByText('selectLang')).toBeInTheDocument();
         fireEvent.click(screen.getByText('English'));
@@ -110,11 +116,13 @@ describe('Layout', () => {
     it('starts collapsed when localStorage has collapsed=1', async () => {
         window.localStorage.setItem('layout.sidebarCollapsed', '1');
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         expect(screen.getByLabelText('Expand Navigation')).toBeInTheDocument();
     });
 
     it('calls fetchFingerPrints on mount', async () => {
         await act(async () => { render(<Layout Child={DummyChild} />); });
+        await waitFor(() => expect(screen.queryByText('layout.backendLoading')).not.toBeInTheDocument(), { timeout: 3000 });
         expect(mockFetchFingerPrints).toHaveBeenCalled();
     });
 });

client/src/utils/api.js

@@ -268,6 +268,10 @@ class APIManager {
         console.log('[api] checkWebSocket response:', res?.data);
         return res.data;
     }
+    async checkReadiness(){
+        const res = await axios.get(`${this.baseUrl}/readiness`, { timeout: 3000 });
+        return res.data;
+    }
     async getTaskStatus(taskNames = []) {
         const res = await axios.post(`${this.baseUrl}/getTaskStatus`, { taskNames });
         return res.data;

server/router.js

@@ -238,6 +238,49 @@ router.get('/checkWebSocket',async(req,res)=>{
   const message = await taskService.checkWebSocket();
   res.send(message);
 });
+
+// Comprehensive readiness check — returns true only when ALL backend services are up
+router.get('/readiness', async (req, res) => {
+  const checks = { server: true, webSocket: false, dbservice: false, toolService: false };
+  try {
+    // WebSocket
+    const wsResult = await taskService.checkWebSocket();
+    checks.webSocket = !!(wsResult && wsResult.success !== false);
+  } catch (_) {}
+  try {
+    // dbservice (memory/knowledge)
+    const dbRes = await memoryService.handleHealth(
+      { method: 'GET' },
+      { status: () => ({ json: (d) => d }), json: (d) => d }
+    );
+    // handleHealth is an Express handler, use proxyToDbService directly
+    const http = require('http');
+    await new Promise((resolve) => {
+      const r = http.get('http://127.0.0.1:30002/health', { timeout: 2000 }, (resp) => {
+        checks.dbservice = resp.statusCode === 200;
+        resp.resume();
+        resolve();
+      });
+      r.on('error', () => resolve());
+      r.on('timeout', () => { r.destroy(); resolve(); });
+    });
+  } catch (_) {}
+  try {
+    // toolService
+    const http = require('http');
+    await new Promise((resolve) => {
+      const r = http.get('http://127.0.0.1:30004/health', { timeout: 2000 }, (resp) => {
+        checks.toolService = resp.statusCode === 200;
+        resp.resume();
+        resolve();
+      });
+      r.on('error', () => resolve());
+      r.on('timeout', () => { r.destroy(); resolve(); });
+    });
+  } catch (_) {}
+  const allReady = checks.server && checks.webSocket && checks.dbservice && checks.toolService;
+  res.send({ success: allReady, checks });
+});
 router.post('/getTaskStatus', async (req, res) => {
   const { taskNames } = req.body || {};
   const message = taskService.getTaskRunningStatus(taskNames);