|
| 1 | +# Frontend-Backend Communication (React Query Architecture) |
| 2 | + |
| 3 | +This document describes the current architecture and all communication points between the frontend and backend in the Pad.ws application, following the React Query refactor. All API interactions are now managed through React Query hooks, providing deduplication, caching, polling, and robust error handling. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Overview of Communication Architecture |
| 8 | + |
| 9 | +- **All frontend-backend communication is handled via React Query hooks.** |
| 10 | +- **API calls are centralized in `src/frontend/src/api/hooks.ts` and `apiUtils.ts`.** |
| 11 | +- **No custom context providers for authentication or workspace state are used; hooks are called directly in components.** |
| 12 | +- **Error and loading states are managed by React Query.** |
| 13 | +- **Mutations (e.g., saving data, starting/stopping workspace) automatically invalidate relevant queries.** |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## 2. Authentication |
| 18 | + |
| 19 | +### 2.1. Authentication Status |
| 20 | + |
| 21 | +- **Hook:** `useAuthCheck` |
| 22 | +- **Endpoint:** `GET /api/workspace/state` |
| 23 | +- **Usage:** Determines if the user is authenticated. Returns `true` if authenticated, `false` if 401 Unauthorized. |
| 24 | +- **Example:** |
| 25 | + ```typescript |
| 26 | + import { useAuthCheck } from "./api/hooks"; |
| 27 | + const { data: isAuthenticated = true } = useAuthCheck(); |
| 28 | + ``` |
| 29 | +- **UI:** If `isAuthenticated` is `false`, the login modal (`AuthModal`) is displayed. |
| 30 | + |
| 31 | +### 2.2. Login/Logout |
| 32 | + |
| 33 | +- **Login:** Handled via OAuth redirects (e.g., `/auth/login?kc_idp_hint=google`). |
| 34 | +- **Logout:** Handled via redirect to `/auth/logout`. |
| 35 | +- **No direct API call from React Query; handled by browser navigation.** |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## 3. User Profile |
| 40 | + |
| 41 | +- **Hook:** `useUserProfile` |
| 42 | +- **Endpoint:** `GET /api/user/me` |
| 43 | +- **Usage:** Fetches the authenticated user's profile. |
| 44 | +- **Example:** |
| 45 | + ```typescript |
| 46 | + import { useUserProfile } from "./api/hooks"; |
| 47 | + const { data: userProfile, isLoading, error } = useUserProfile(); |
| 48 | + ``` |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## 4. Workspace Management |
| 53 | + |
| 54 | +### 4.1. Workspace State |
| 55 | + |
| 56 | +- **Hook:** `useWorkspaceState` |
| 57 | +- **Endpoint:** `GET /api/workspace/state` |
| 58 | +- **Usage:** Polls workspace state every 5 seconds. |
| 59 | +- **Example:** |
| 60 | + ```typescript |
| 61 | + import { useWorkspaceState } from "./api/hooks"; |
| 62 | + const { data: workspaceState, isLoading, error } = useWorkspaceState(); |
| 63 | + ``` |
| 64 | + |
| 65 | +### 4.2. Start/Stop Workspace |
| 66 | + |
| 67 | +- **Hooks:** `useStartWorkspace`, `useStopWorkspace` |
| 68 | +- **Endpoints:** `POST /api/workspace/start`, `POST /api/workspace/stop` |
| 69 | +- **Usage:** Mutations to start/stop the workspace. On success, invalidate and refetch workspace state. |
| 70 | +- **Example:** |
| 71 | + ```typescript |
| 72 | + import { useStartWorkspace, useStopWorkspace } from "./api/hooks"; |
| 73 | + const { mutate: startWorkspace } = useStartWorkspace(); |
| 74 | + const { mutate: stopWorkspace } = useStopWorkspace(); |
| 75 | + // Usage: startWorkspace(); stopWorkspace(); |
| 76 | + ``` |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +## 5. Canvas Data Management |
| 81 | + |
| 82 | +### 5.1. Load Canvas |
| 83 | + |
| 84 | +- **Hooks:** `useCanvas`, `useDefaultCanvas` |
| 85 | +- **Endpoints:** `GET /api/canvas`, `GET /api/canvas/default` |
| 86 | +- **Usage:** Loads user canvas data; falls back to default if not available or on error. |
| 87 | +- **Example:** |
| 88 | + ```typescript |
| 89 | + import { useCanvas, useDefaultCanvas } from "./api/hooks"; |
| 90 | + const { data: canvasData, isError } = useCanvas(); |
| 91 | + const { data: defaultCanvasData } = useDefaultCanvas({ enabled: isError }); |
| 92 | + ``` |
| 93 | + |
| 94 | +### 5.2. Save Canvas |
| 95 | + |
| 96 | +- **Hook:** `useSaveCanvas` |
| 97 | +- **Endpoint:** `POST /api/canvas` |
| 98 | +- **Usage:** Saves canvas data. Only called if user is authenticated. |
| 99 | +- **Example:** |
| 100 | + ```typescript |
| 101 | + import { useSaveCanvas } from "./api/hooks"; |
| 102 | + const { mutate: saveCanvas } = useSaveCanvas(); |
| 103 | + // Usage: saveCanvas(canvasData); |
| 104 | + ``` |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## 6. Error Handling |
| 109 | + |
| 110 | +- **All API errors are handled by React Query and the `fetchApi` utility.** |
| 111 | +- **401 Unauthorized:** Triggers unauthenticated state; login modal is shown. |
| 112 | +- **Other errors:** Exposed via `error` property in hook results; components can display error messages or fallback UI. |
| 113 | +- **Example:** |
| 114 | + ```typescript |
| 115 | + const { data, error, isLoading } = useWorkspaceState(); |
| 116 | + if (error) { /* Show error UI */ } |
| 117 | + ``` |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## 7. API Utility Functions |
| 122 | + |
| 123 | +- **File:** `src/frontend/src/api/apiUtils.ts` |
| 124 | +- **Functions:** `fetchApi`, `handleResponse` |
| 125 | +- **Purpose:** Centralizes fetch logic, error handling, and credentials management for all API calls. |
| 126 | + |
| 127 | +--- |
| 128 | + |
| 129 | +## 8. Summary |
| 130 | + |
| 131 | +- **All frontend-backend communication is now declarative and managed by React Query hooks.** |
| 132 | +- **No legacy context classes or direct fetches remain.** |
| 133 | +- **API logic is centralized, maintainable, and testable.** |
| 134 | +- **Error handling, caching, and polling are handled automatically.** |
| 135 | +- **UI components react to hook state for loading, error, and data.** |
| 136 | + |
| 137 | +This architecture ensures robust, efficient, and maintainable communication between the frontend and backend. |
0 commit comments