Skip to content

Self-improving AI Employees for everyone

docs(frontend): Phase 7 - record post-antd cleanup outcomes

trohitgc02be2d856a5
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 63330350..9a1888c2 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -140,11 +140,15 @@ client/src/
├── hooks/
│ ├── useAppTheme.ts # Bridges ThemeContext + Solarized/Dracula palettes
│ ├── useCatalogueQuery.ts # TanStack Query + idb-keyval warm-start (exemplar)
+│ ├── useWorkflowsQuery.ts # Workflow list + save/delete mutations (Query)
+│ ├── useNodeParamsQuery.ts # Per-node parameter Query + save mutation
+│ ├── useUserSettingsQuery.ts # user_settings row Query + save mutation
│ ├── useApiKeys.ts # WS-based API key CRUD
│ ├── useApiKeyValidation.ts # Provider-specific validation helpers
│ ├── useComponentPalette.ts / useDragAndDrop.ts / useExecution.ts
-│ ├── useOnboarding.ts / useParameterPanel.ts / usePricing.ts
-│ ├── useToolSchema.ts / useWhatsApp.ts / useAndroidOperations.ts
+│ ├── useOnboarding.ts # Reads via useUserSettingsQuery; writes via mutation
+│ ├── useParameterPanel.ts # Thin orchestrator over useNodeParamsQuery + save mutation
+│ ├── usePricing.ts / useToolSchema.ts / useWhatsApp.ts / useAndroidOperations.ts
│ └── useCopyPaste.ts / useRename.ts
│
├── store/
@@ -152,6 +156,9 @@ client/src/
│ └── useCredentialRegistry.ts # UI-only: selectedId + paletteOpen + query
│
├── lib/
+│ ├── queryClient.ts # Module-singleton QueryClient so imperative
+│ │ # code (Zustand actions) can invalidate without
+│ │ # going through React context.
│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)
│
├── styles/
@@ -346,6 +353,23 @@ See [ui_migration_plan.md](./ui_migration_plan.md) Phase 6.
- All modifying operations go through WebSocket — REST is reserved for auth + webhooks.
- No polling. If a component wants fresh data, call `sendRequest` once (or use TanStack Query with `staleTime: Infinity` + manual `invalidate`).
+## Ownership boundary: TanStack Query vs Zustand vs WebSocketContext
+
+This is the rule that keeps the data layer schema-driven instead of imperatively glued together.
+
+| Owns | What goes here | Examples |
+|---|---|---|
+| **TanStack Query** | Anything the server has authoritative state for. List / single-record / settings reads. Mutations that change server state. | `useWorkflowsQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`, `useCatalogueQuery`, `useSaveWorkflowMutation`, `useSaveNodeParamsMutation`, `useSaveUserSettingsMutation` |
+| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId` |
+| **`useState` / `useReducer`** | Per-component transient state. Form-field drafts. Hover/focus. | text-input drafts, dropdown-open, inline-edit toggles |
+| **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (node status, workflow progress, android status). | `nodeStatuses`, `androidStatus`, `consoleLogs`, broadcast streams |
+
+**Hard rules:**
+- A list of server records (`workflows`, `nodeParameters`, `userSettings`, `credentialCatalogue`) lives in TanStack Query. Never duplicate it in Zustand. Phase-1 follow-up commit `c3a7aa4` removed `savedWorkflows` from `useAppStore` for exactly this reason.
+- Imperative WebSocket request/response inside a component (`useEffect` + `sendRequest` + `setState`) is a code smell — wrap it in a `useQuery` hook. Phase-2 commit `b2b6fba` did this for `useParameterPanel` and `useOnboarding`.
+- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list. Mutations that need it from non-React code use the `queryClient` singleton at [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts).
+- Schema metadata for parameter behavior (selectors, validators, dynamic options) belongs in the node-definition `typeOptions`, NOT in `parameter.name === '...'` checks inside `ParameterRenderer`. Phase-5 commit `8353c48` introduced `typeOptions.loadOptionsMethod` for the WhatsApp selectors as the canonical pattern.
+
## Theme + canvas chrome
[index.css](../client/src/index.css) also styles React Flow, scrollbars, and dot grid against the CSS-var palette. No inline hex codes in theme-sensitive surfaces — everything references `hsl(var(--...))` so dark mode flips cleanly.
diff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ui_migration_plan.md
index 08e32e96..e0c80ca2 100644
--- a/docs-internal/ui_migration_plan.md
+++ b/docs-internal/ui_migration_plan.md
@@ -24,6 +24,29 @@
- `grep -rln "styled-components" client/src/` → **0**
- `pnpm build` green throughout all 17 commits on `feature/credentials-scaling-v2`
+## Post-antd cleanup (April 2026)
+
+A second audit (3 parallel sub-agents) flagged tribal patterns that survived the antd retirement and didn't match the schema-driven design system. A focused 5-phase follow-up plan ([typed-splashing-crown](../../../.claude/plans/typed-splashing-crown.md)) addresses them:
+
+| Follow-up phase | Status | Commit | What it removes |
+|---|---|---|---|
+| 1 — Workflow list to TanStack Query | ✅ done | `c3a7aa4` | `savedWorkflows` array + `loadSavedWorkflows` action duplicating server data in Zustand |
+| 2 — `useParameterPanel` / `useOnboarding` to Query hooks | ✅ done | `b2b6fba` | hand-rolled `useState + useEffect` over `WebSocketContext.sendRequest` |
+| 3 — Theme tokens to CSS vars (kickoff) | ✅ done | `8b19808` | `theme.ts` deprecation banner + `AIAgentNode` PHASE_CONFIG hex literals (bulk migration of `GenericNode` / `SettingsPanel` / `BaseChatModelNode` deferred) |
+| 4 — `SettingsPanel` to zod + Phase-2 hooks | ✅ done | `2901f0a` | duplicated camel↔snake mappers + hand-rolled load/save WS calls |
+| 5 — Schema-drive WhatsApp selectors | ✅ done | `8353c48` | `parameter.name === 'group_id'` / `'channel_jid'` / `'senderNumber'` branches in `ParameterRenderer` (now `typeOptions.loadOptionsMethod`) |
+
+**What's still tribal (deferred):**
+- Bulk inline-style migration in `GenericNode`, `SettingsPanel` non-button styles, `BaseChatModelNode`. The Tailwind classes are wired and the deprecation banner is in place; per-component conversion is mechanical but visual-regression-prone, so left for follow-up commits with browser verification.
+- `parameter.name === 'apiKey'` / `'model'` specials in `ParameterRenderer` — same migration path (`typeOptions.loadOptionsMethod = 'providerModels'` etc.), parked until the WhatsApp pattern proves stable.
+- `ConsolePanel` 11 × `useState` → `useReducer` + zod schema. Independent edit-state domain; won't be touched until a behavior change forces it.
+
+**New canonical patterns introduced:**
+- Workflows + node params + user settings live in TanStack Query (`useWorkflowsQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`), not Zustand or component-local state.
+- Module-singleton `QueryClient` at [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts) so imperative code (Zustand actions) can invalidate without going through React context.
+- Settings + onboarding share one cached server read (`['userSettings']`).
+- WhatsApp group / channel / member selectors dispatch from `typeOptions.loadOptionsMethod` instead of parameter-name string compares — schema is the source of truth.
+
## Context
The MachinaOs frontend was coupled to Ant Design (40 files, 187-line theme file, `ConfigProvider` at root). Pre-migration audit + research docs (now deleted; see git history under commit `4cb3dd9` if needed) prescribed shadcn/ui (canonical components copied via CLI registry) + Radix primitives + Tailwind 4 + JSON Forms for a schema-driven inspector. Phase 0/1 commits (`2209dba`, `7ac69fe`) included hand-written primitives and a toast facade — those got deleted as part of corrected Phase 0 (`cdeebb4`).