Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(frontend): Phase 7 - record post-antd cleanup outcomes
trohitgc02be2d856a5
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 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.mdindex 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.+## ContextThe 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`).