Skip to content

Self-improving AI Employees for everyone

docs: sweep md files for Wave 3 backend-schema + AlertDialog patterns

trohitgb6ee1e20e57a
diff --git a/CLAUDE.md b/CLAUDE.md
index 4b20693c..67c1c2d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,8 +9,9 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| Document | Description |
|----------|-------------|
-| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar. |
-| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Phases 0-5, 7 done; phase 6 (ParameterRenderer → JSON Forms) deferred. |
+| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar, ownership boundary, `uiHints` catalogue. |
+| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Waves 1–3 done; Phase 6 (ParameterRenderer → widget registry) deferred pending backend `get_node_spec`. |
+| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Wave 3 decision: node output shapes live on the backend (Pydantic → JSON Schema) and the frontend fetches them lazy, n8n-style. Defines `GET /api/schemas/nodes/{type}.json` + `get_node_output_schema` WS handler. |
| **[Node Creation Guide](./docs-internal/node_creation.md)** | Complete guide for creating new nodes (frontend definitions, backend handlers, config nodes, triggers) |
| **[AI Tool Node Guide](./docs-internal/ai_tool_node_creation.md)** | Detailed guide for creating dedicated AI Agent tool nodes (schemas, handlers, toolkits) |
| **[Specialized Agent Guide](./docs-internal/specialized_agent_node_creation.md)** | Guide for creating specialized AI agents (Android, Coding, Web, Task, Social, Travel, Tool, Productivity, Payments, Consumer) with full AI configuration |
@@ -2210,28 +2211,34 @@ def extract_thinking_from_response(response, provider: str) -> Optional[str]:
#### Output Schema for Connected Nodes
The `thinking` field is available in Input Data & Variables for downstream nodes. This schema applies to all AI nodes including chat models and specialized agents.
-```typescript
-// In InputSection.tsx
-const sampleSchemas = {
- ai: {
- response: 'string',
- thinking: 'string', // Available for drag-and-drop mapping
- model: 'string',
- provider: 'string',
- finish_reason: 'string',
- timestamp: 'string'
- }
-};
+**Source of truth (Wave 3, April 2026):** runtime output shapes live on the **backend**, not the frontend. Declared in Pydantic models at `server/services/node_output_schemas.py` and served lazy via `GET /api/schemas/nodes/{node_type}.json` / the `get_node_output_schema` WebSocket handler. The frontend's InputSection prefers real execution data, falls back to the backend schema, then an empty state. See [docs-internal/schema_source_of_truth_rfc.md](./docs-internal/schema_source_of_truth_rfc.md).
-// Node types that use the AI output schema
-const aiAgentTypes = [
- 'aiAgent', 'chatAgent',
- 'android_agent', 'coding_agent', 'web_agent', 'task_agent', 'social_agent',
- 'travel_agent', 'tool_agent', 'productivity_agent', 'payments_agent', 'consumer_agent'
-];
-const isAI = nodeTypeLower.includes('chatmodel') || aiAgentTypes.includes(nodeType);
+```python
+# server/services/node_output_schemas.py
+class AIAgentOutput(_OutputBase):
+ response: Optional[str] = None
+ thinking: Optional[str] = None # Available for drag-and-drop mapping
+ model: Optional[str] = None
+ provider: Optional[str] = None
+ finish_reason: Optional[str] = None
+ timestamp: Optional[str] = None
+
+# Shared across every LLM-backed agent + chat model:
+_AGENT_TYPES = ['aiAgent', 'chatAgent', 'android_agent', 'coding_agent',
+ 'web_agent', 'task_agent', 'social_agent', 'travel_agent',
+ 'tool_agent', 'productivity_agent', 'payments_agent',
+ 'consumer_agent', 'autonomous_agent', 'orchestrator_agent',
+ 'ai_employee', 'rlm_agent', 'claude_code_agent', 'deep_agent']
+_CHAT_MODEL_TYPES = ['openaiChatModel', 'anthropicChatModel', 'geminiChatModel', ...]
+NODE_OUTPUT_SCHEMAS = {
+ **{t: AIAgentOutput for t in _AGENT_TYPES},
+ **{t: AIAgentOutput for t in _CHAT_MODEL_TYPES},
+ # ...
+}
```
+Adding a new node type's output shape: define one Pydantic model, register it in `NODE_OUTPUT_SCHEMAS`. Zero frontend change.
+
#### UI Display (`client/src/components/ui/NodeOutputPanel.tsx`)
- **ThinkingBlock Component**: Collapsible display for thinking content
- **Default Expanded**: Thinking block is expanded by default when present
@@ -4746,37 +4753,33 @@ whatsappReceive: {
}
```
-#### Output Schema (`client/src/components/parameterPanel/InputSection.tsx`)
-Provides draggable variables for downstream nodes:
-```typescript
-const sampleSchemas = {
- whatsapp: {
- message_id: 'string',
- sender: 'string',
- sender_phone: 'string', // Resolved phone number (Go RPC resolves LIDs before sending event)
- chat_id: 'string',
- message_type: 'string',
- text: 'string',
- timestamp: 'string',
- is_group: 'boolean',
- is_from_me: 'boolean',
- push_name: 'string',
- is_forwarded: 'boolean',
- forwarding_score: 'number',
- media: 'object',
- group_info: {
- group_jid: 'string',
- sender_jid: 'string',
- sender_phone: 'string', // Resolved phone number (Go RPC resolves LIDs)
- sender_name: 'string'
- },
- newsletter_meta: {
- edit_ts: 'number',
- original_ts: 'number'
- }
- }
-};
-```
+#### Output Schema (backend, `server/services/node_output_schemas.py`)
+Runtime output shapes live on the backend and are fetched lazy by InputSection per the Wave 3 source-of-truth decision. The WhatsApp Receive schema:
+```python
+class WhatsAppGroupInfo(BaseModel):
+ group_jid: Optional[str] = None
+ sender_jid: Optional[str] = None
+ sender_phone: Optional[str] = None # Resolved phone number (Go RPC resolves LIDs before sending event)
+ sender_name: Optional[str] = None
+
+class WhatsAppReceiveOutput(_OutputBase):
+ message_id: Optional[str] = None
+ sender: Optional[str] = None
+ sender_phone: Optional[str] = None
+ chat_id: Optional[str] = None
+ message_type: Optional[str] = None
+ text: Optional[str] = None
+ timestamp: Optional[str] = None
+ is_group: Optional[bool] = None
+ is_from_me: Optional[bool] = None
+ push_name: Optional[str] = None
+ media: Optional[dict] = None
+ group_info: Optional[WhatsAppGroupInfo] = None
+ newsletter_meta: Optional[dict] = None
+
+NODE_OUTPUT_SCHEMAS["whatsappReceive"] = WhatsAppReceiveOutput
+```
+Served via `GET /api/schemas/nodes/whatsappReceive.json` + `get_node_output_schema` WS handler. See [docs-internal/schema_source_of_truth_rfc.md](./docs-internal/schema_source_of_truth_rfc.md).
### Task Trigger Node
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 6f2fc1fe..f59bbc44 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -365,10 +365,12 @@ This is the rule that keeps the data layer schema-driven instead of imperatively
| **`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).
+- A list of server records (`workflows`, `nodeParameters`, `userSettings`, `credentialCatalogue`, `userSkills`, node output schemas) lives in TanStack Query. Never duplicate it in Zustand. Phase-1 follow-up commit `c3a7aa4` removed `savedWorkflows` from `useAppStore` for exactly this reason; Wave 3 commit `7706afb` did the same for `userSkills` in MasterSkillEditor.
+- Imperative WebSocket request/response inside a component (`useEffect` + `sendRequest` + `setState`) is a code smell — wrap it in a `useQuery` hook. Inline the hook at the top of the consuming file when there's exactly one consumer (Wave 2/3 colocation rule); promote to `client/src/hooks/` when a second consumer appears. Phase-2 commit `b2b6fba` did this for `useParameterPanel` and `useOnboarding`; Wave 3 commits `2c5f227` / `7706afb` / `327f792` followed the same pattern inline inside MiddleSection / MasterSkillEditor / InputSection.
+- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list or call a local refetch helper. 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.
+- **Runtime output shapes for the Input panel's variable list live on the backend** via Pydantic models in `server/services/node_output_schemas.py`. The frontend fetches them lazy via `get_node_output_schema`; real execution data takes precedence. See the "Node output shape" section below and [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).
+- **Never hand-roll a modal backdrop.** Destructive confirmations use `<AlertDialog>`; composite panels use the `Modal.tsx` primitive on top of shadcn `<Dialog>`. A raw `position: fixed; background: rgba(0,0,0,0.5)` in new code should not pass review.
## Schema-driven node + panel hints
@@ -425,13 +427,14 @@ inspector/
The DIY widget registry (RHF + zod + a tester+rank dispatch) is modeled on n8n's monolithic `ParameterInput.vue`. Library-survey research preferred this over @jsonforms / @rjsf — bundle delta ≤ +50 KB gz vs +60–110 KB for any framework option, and shadcn theming would have to be hand-authored against any of them. `@rjsf/core` v6 + `@rjsf/shadcn` is the documented escape hatch if collection recursion bites.
-## Reusable component primitives (Wave 2)
+## Reusable component primitives
| File | When to use |
|---|---|
| [client/src/components/ui/action-button.tsx](../client/src/components/ui/action-button.tsx) | Colored "soft" toolbar button (Run / Save / Cancel / Reset / Stop). One `tone` prop drives bg/border/text against a fixed dracula palette via static Tailwind classes. Replaces the `actionButtonStyle(color, isDisabled)` style helper that was copy-pasted across 4 files. |
+| [client/src/components/ui/alert-dialog.tsx](../client/src/components/ui/alert-dialog.tsx) | Confirmation / destructive-action modals. **Never hand-roll a `position: fixed; background: rgba(0,0,0,0.5)` backdrop** — use `<AlertDialog open onOpenChange>` with `AlertDialogHeader` / `AlertDialogDescription` / `AlertDialogFooter`. Focus trap, escape-to-close, and `role="alertdialog"` come from Radix. MiddleSection Clear Memory + Reset Skill dialogs are the canonical consumers (Wave 3 commit `61bf23c`). |
| [client/src/components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx) | The `<Toaster />` mount — call `import { toast } from 'sonner'` directly at use sites; do not wrap. |
-| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. |
+| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. For destructive confirmations prefer `AlertDialog` above. |
| `client/src/components/ui/{button,input,select,switch,checkbox,form,…}.tsx` | shadcn-generated primitives. Add new ones via `npx shadcn@latest add <name>`. Don't re-implement what the registry ships. |
## Theme + canvas chrome
diff --git a/docs-internal/new_service_integration.md b/docs-internal/new_service_integration.md
index c7897c42..8d040215 100644
--- a/docs-internal/new_service_integration.md
+++ b/docs-internal/new_service_integration.md
@@ -669,30 +669,25 @@ async def _execute_{operation1}(args: Dict[str, Any], node_params: Dict[str, Any
---
-## Step 8: Output Schemas
+## Step 8: Output Schemas (backend)
-Add output schemas in `client/src/components/parameterPanel/InputSection.tsx`:
+Output shapes live on the backend — the editor fetches them lazy (see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md)). Add one Pydantic model per node type to [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) and register it:
-```typescript
-const sampleSchemas: Record<string, Record<string, string>> = {
- // ... existing schemas
-
- {service}: {
- result_id: 'string',
- field1: 'string',
- field2: 'array',
- timestamp: 'string',
- },
-};
+```python
+# server/services/node_output_schemas.py
-// Add node type detection
-const {service}Types = ['{operation1}Node', '{operation2}Node'];
-const is{Service} = {service}Types.includes(nodeType);
-if (is{Service}) {
- schema = sampleSchemas.{service};
-}
+class YourServiceOutput(_OutputBase):
+ result_id: Optional[str] = None
+ field1: Optional[str] = None
+ field2: Optional[list] = None
+ timestamp: Optional[str] = None
+
+# In NODE_OUTPUT_SCHEMAS:
+NODE_OUTPUT_SCHEMAS["yourServiceOperationNode"] = YourServiceOutput
```
+InputSection consumes these automatically via `GET /api/schemas/nodes/{node_type}.json`. No frontend change needed. Shape shared across operations? Assign the same model to multiple keys in `NODE_OUTPUT_SCHEMAS` (see how `_SEARCH_TYPES` aliases `SearchOutput`).
+
---
## Step 9: Credentials Modal
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 6935c9ea..947e7518 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -640,32 +640,22 @@ outputs: [{
}]
```
-### Sample Schemas for Common Nodes
+### Declaring the runtime output shape (backend)
-Add sample schemas in `InputSection.tsx` for better drag-and-drop UX:
+The node's output shape lives on the **backend** — the frontend fetches it lazy (see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md)). Add a Pydantic model to [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) and register it in `NODE_OUTPUT_SCHEMAS`:
-```typescript
-const sampleSchemas: Record<string, Record<string, string>> = {
- aiAgent: {
- response: 'string',
- model: 'string',
- provider: 'string',
- iterations: 'number',
- timestamp: 'string'
- },
- httpRequest: {
- status: 'number',
- data: 'object',
- headers: 'object'
- },
- yourNewNode: {
- field1: 'string',
- field2: 'number',
- // ... document your output fields
- }
-};
+```python
+# server/services/node_output_schemas.py
+class YourNewNodeOutput(_OutputBase):
+ field1: Optional[str] = None
+ field2: Optional[int] = None
+ # ...
+
+NODE_OUTPUT_SCHEMAS["yourNewNode"] = YourNewNodeOutput
```
+That's it — the editor's Input panel picks it up on next open via `GET /api/schemas/nodes/yourNewNode.json`. No frontend change. If you skip this, InputSection falls back to real run data (once the node executes) and then to an empty `{ data: 'any' }` state.
+
---
## Nodes Without Output Handles
diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.md
index 17ab2227..0d84ed07 100644
--- a/docs-internal/schema_source_of_truth_rfc.md
+++ b/docs-internal/schema_source_of_truth_rfc.md
@@ -1,6 +1,15 @@
# Schema source of truth — RFC
-**Status:** accepted · **Owner:** frontend + backend platform · **Date:** 2026-04-14
+**Status:** ✅ **implemented** · **Owner:** frontend + backend platform · **Date:** 2026-04-14 · **Landed across:** commits `cd252c1` → `4a4a439` (8 commits on `feature/credentials-scaling-v2`)
+
+## Landed outcome
+
+- Backend registry seeded with **98 Pydantic models** in [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) covering every node type the deleted `sampleSchemas` map covered, plus all 18 specialized agents and 9 chat models.
+- `GET /api/schemas/nodes/{node_type}.json` serves static JSON Schema (Cache-Control `public, max-age=86400`). 404 for unknown types.
+- `get_node_output_schema` WebSocket handler for authenticated editor fetches.
+- [InputSection.tsx](../client/src/components/parameterPanel/InputSection.tsx) consumes schemas lazy via `queryClient.fetchQuery(['nodeOutputSchema', nodeType])`, in-memory cache only. **1,673 → 972 LOC** (−701). sampleSchemas map, 20 `isXxxNode` detection constants, and 60-line pattern-match chain all gone.
+- `outputSchema` field removed from `INodeTypeDescription` — the frontend type no longer has any shape-describing surface for runtime output.
+- Adding a new node type's output shape: one Pydantic model in `node_output_schemas.py`. Zero frontend change.
## Problem
diff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ui_migration_plan.md
index 7b4fbbae..9a3ca947 100644
--- a/docs-internal/ui_migration_plan.md
+++ b/docs-internal/ui_migration_plan.md
@@ -86,17 +86,18 @@ Under that finding, the in-flight Wave 3 Phase 1 was reversed: the backend owns
| 1a — Revert frontend outputSchema annotations | ✅ done | `cd252c1`, `5866821` | 30-file frontend annotation revert; `outputSchema` field removed from `INodeTypeDescription`; the 7 Wave-2-canary annotations (start/chatTrigger/taskTrigger/simpleMemory/python+js+ts executors) also removed — same principle |
| 1b — Backend schema registry + endpoint | ✅ done | `0d98c88`, `4a4a439` | `server/services/node_output_schemas.py` — **98 node-type entries** across agents / chat models / triggers / memory / code executors / Google Workspace / WhatsApp / search / location / filesystem / HTTP / Android / documents / proxy / email / telegram / twitter / social / browser / apify / crawlee / cronScheduler. Pydantic models colocated. `GET /api/schemas/nodes/{node_type}.json` (Cache-Control public, max-age=86400) + `get_node_output_schema` WS handler |
| 1c — Frontend three-tier dispatch + delete sampleSchemas | ✅ done | `327f792`, `4a4a439` | `InputSection.tsx` 1,673 → 972 LOC (−701). `sampleSchemas` map + 20-line `is{Android,Google,…}Node` detection constants + 60-line pattern-match else-if chain all gone. Schema precedence: real run data → backend fetch (cached in TanStack Query, in-memory only, matches n8n's `schemaPreview.store` pattern) → `{ data: 'any' }` empty |
-| 2 — MiddleSection decompose | 🟡 partial | `2c5f227` | Two tractable wins landed: `sendRequest('get_user_settings')` → shared `useUserSettingsQuery`; `sendRequest('configure_compaction')` threshold-edit → TanStack `useMutation`. Full 6-sub-panel extraction deferred — 1,248 LOC with deeply-tangled useEffect chains needs in-browser verification |
-| 3 — MasterSkillEditor decompose | ⏸ deferred | — | 1,133 LOC + 8 imperative `sendRequest + setState` sites across multiple useEffect chains + native capture-phase keydown escape. Safe decomposition requires UI smoke testing across folder-scan / user-skill CRUD / skill-content fetch |
+| 2 — MiddleSection decompose | 🟡 partial | `2c5f227`, `61bf23c` | Three wins landed: (a) `sendRequest('get_user_settings')` → shared `useUserSettingsQuery`; (b) `sendRequest('configure_compaction')` threshold-edit → TanStack `useMutation`; (c) both hand-rolled confirmation modals (Clear Memory, Reset Skill) → shadcn `AlertDialog` primitives — 180 LOC of inline modal JSX + 40 LOC of trigger-button styles gone, accessibility (focus trap / escape / aria) from Radix. Net: 1,248 → 1,120 LOC. Full 6-sub-panel extraction still deferred for the deeply-tangled connected-skills / token-usage / console-output regions |
+| 3 — MasterSkillEditor decompose | 🟡 partial | `7706afb` | One read-path migration landed: `get_user_skills` imperative fetch → inline `useQuery(['userSkills'])` + `invalidateUserSkills()` helper. The `useState(userSkills)` + `useCallback(fetchUserSkills)` + bootstrap `useEffect` + two `await fetchUserSkills()` call sites all collapse into one query hook with automatic invalidation on save / delete. Three remaining imperative sites (folder list, folder scan, skill content fetch) still pending |
| 4 — ConsolePanel Tailwind sweep | ⏸ deferred | — | 58 inline-style blocks, dynamic resize/layout behaviour. Wave 2 Phase 3 already fixed the state architecture (zod prefs + usePanelResize); visual cleanup is the remaining debt |
| 5 — Docs | ✅ done | this commit | This section + frontend_architecture.md updates |
-**Wave 3 numbers:**
-- Frontend LOC: `InputSection.tsx` −701; `MiddleSection.tsx` −5 + structural cleanup.
-- Frontend `sendRequest + setState` anti-patterns: 2 retired (1 in MiddleSection memory-window-size seed, 1 in compaction threshold save).
+**Wave 3 numbers (cumulative across all 10 commits):**
+- Frontend LOC: `InputSection.tsx` −701; `MiddleSection.tsx` −133 (128 from AlertDialog + 5 from Query-hook swaps); `MasterSkillEditor.tsx` net +7 with one imperative fetch retired.
+- Frontend `sendRequest + setState` anti-patterns retired: **5** — memory-window-size seed, compaction threshold save, `get_user_settings` pre-seed, plus the two modal stacks moved to declarative Radix primitives, plus `get_user_skills` in MasterSkillEditor.
+- Hand-rolled dialog stacks replaced: 2 → shadcn `AlertDialog` (focus trap / escape / aria roles from Radix).
- Backend: +2 files (`node_output_schemas.py`, `routers/schemas.py`), +1 WS handler, +1 router registration. **98 Pydantic models** seeded.
-- `pnpm exec tsc --noEmit` green throughout all 8 commits.
-- New frontend files: 0.
+- `pnpm exec tsc --noEmit` green throughout all 10 commits.
+- New frontend files: **0**.
**Architectural delta (permanent):**
- Node output shapes now live on the backend **exclusively**. New node types get a Pydantic model in `server/services/node_output_schemas.py` — no frontend change needed.