Dumb Client Implementation Guide

Overview

The dumb client is a thin UI layer that talks directly to the edge proxy through a JSON API. In the current implementation, the client does not manage local crypto state in useDesktopSession; it stores only token and baseUrl and passes that session object through the repository layer. See web-omni/src/features/desktop-client/hooks/useDesktopSession.ts:13-54.

The current desktop flow is mixed-mode:

1. Load workspaces from the modern route GET /v1/workspaces.
2. Use legacy workspace-scoped note routes for note CRUD.
3. Use the modern route POST /v1/documents/query for search.

That behavior is grounded to web-omni/src/features/desktop-client/DesktopClientApp.tsx:23-57 and web-omni/src/features/desktop-client/lib/documentRepository.ts:311-472.

Key Components

Minimal bootstrap

import DesktopClientApp from "@/features/desktop-client/DesktopClientApp";

export default function App() {
  return <DesktopClientApp />;
}

1. Session and authentication

The desktop client session contains only:

• token
• baseUrl

setSession(token, baseUrl) persists both values and clearSession() removes them. See web-omni/src/features/desktop-client/hooks/useDesktopSession.ts:17-43.

A minimal request helper should include the bearer token:

const headers = new Headers({
  Authorization: `Bearer ${session.token}`,
});

Only add X-Proxy-Decrypt or X-Client-Key if your client explicitly needs proxy-side decryption behavior documented in core-console/content/docs/api-reference/endpoints.mdx:13-66.

2. Workspace loading flow

DesktopClientApp loads workspaces after a session becomes available, selects the first workspace by default, and surfaces loading and empty states. See web-omni/src/features/desktop-client/DesktopClientApp.tsx:23-57.

Repository call:

const workspaces = await listWorkspaces(session);
setWorkspaces(workspaces);
setSelectedWorkspaceId((current) => current || workspaces[0]?.id || "");

This is implemented through listWorkspaces(session) in web-omni/src/features/desktop-client/lib/documentRepository.ts:311-315.

3. Current document workflow

The current desktop client does not use unified document CRUD for create/update/delete. Instead it uses legacy notes endpoints:

• list notes: GET /v1/workspaces/:workspaceId/notes
• get note: GET /v1/workspaces/:workspaceId/notes/:noteId
• create note: POST /v1/workspaces/:workspaceId/notes
• update note: PATCH /v1/workspaces/:workspaceId/notes/:noteId
• delete note: DELETE /v1/workspaces/:workspaceId/notes/:noteId

Grounded to web-omni/src/features/desktop-client/lib/documentRepository.ts:317-387 and web-omni/src/features/desktop-client/lib/documentRepository.ts:422-472.

useDocumentWorkspace wraps those repository calls and manages:

• initial note loading when workspaceId changes
• selected document state
• create/update/delete actions
• search state and result hydration

See web-omni/src/features/desktop-client/hooks/useDocumentWorkspace.ts:32-309.

4. Search workflow

Search is already wired to the modern query route:

• POST /v1/documents/query

That request is implemented in web-omni/src/features/desktop-client/lib/documentRepository.ts:389-420.

This means the current client already spans both compatibility and modern APIs:

• modern for workspace discovery and search
• legacy for note CRUD

5. Guidance for new clients

If you are building a new frontend from scratch:

• Prefer the unified document routes documented in core-console/content/docs/api-reference/endpoints.mdx:302-725.
• Use the legacy notes routes only when you need compatibility with the current desktop note model documented in core-console/content/docs/api-reference/legacy-notes.mdx:6-154.
• Keep the client thin: session management, request orchestration, local UI state, and error handling should live in the frontend; storage transforms and optional response decryption should remain server-side.

Testing the flow

1. Start the web app.
2. Enter a valid token and base URL.
3. Confirm workspace loading succeeds.
4. Open a workspace and verify note list loading succeeds.
5. Create, edit, and delete a note.
6. Run a search and confirm it uses the document query route.

All of those flows are grounded to the current implementation in web-omni/src/features/desktop-client/DesktopClientApp.tsx:14-139, web-omni/src/features/desktop-client/hooks/useDocumentWorkspace.ts:16-309, and web-omni/src/features/desktop-client/lib/documentRepository.ts:311-472.