Flowfile Frontend Conventions

Flowfile frontend conventions

This skill covers flowfile_frontend/ (Vue 3 renderer + Tauri 2 desktop shell) and flowfile_wasm/ (Pyodide browser-only build). It is about how the frontend is put together and where its landmines are — not about the backend it talks to.

When NOT to use this skill

• Backend/core/worker/kernel contracts, secrets format, worker offload wire protocol → flowfile-architecture-contract.
• Adding a new node type end-to-end (backend template, settings schema, add_<type> method) → flowfile-node-development (this skill only covers the frontend half: where the settings .vue file goes and how it's loaded).
• flowfile_frame Python API / codegen → flowfile-frame-and-codegen.
• AI subsystem internals (agents, providers, BYOK) → flowfile-ai-subsystem.
• Running/building the whole stack, Docker Compose, ports → flowfile-build-and-env / flowfile-run-and-operate.
• Env vars and feature flags in detail → flowfile-config-and-flags.
• Writing/running Vitest or Playwright tests → flowfile-testing-and-validation.
• Diagnosing a live symptom step-by-step → flowfile-debugging-playbook.
• Known historical bugs as a searchable archive → flowfile-failure-archaeology.
• Change-control process (drift gates, review, release tags) → flowfile-change-control — nothing here overrides it.

1. Renderer layout & path aliases

Vite's root is flowfile_frontend/src/renderer/ (not the package root), entry index.html (vite.config.mjs:22). Inside that root:

src/renderer/
  main.ts             # bootstrap: createApp, Pinia, router, i18n, Element Plus,
                       # theme init, then setupService -> authService -> auth init -> app.mount("#app")
  config/constants.ts    # axios baseURL + GA OAuth callback URL resolution
  config/environment.ts  # ENV flags derived from NODE_ENV
  lib/desktop.ts       # THE ONLY renderer<->Tauri bridge (see §6)
  app/                 # '@' alias target — all feature code lives here
    App.vue, api/, components/, composables/, features/, layouts/,
    pages/, router/, services/, stores/, types/, utils/, views/

Path aliases exist in three files and must stay in sync — adding or renaming one in only one file silently breaks the dev server, the TypeScript checker, or Vitest (whichever file you forgot):

Router: app/router/index.ts uses createWebHashHistory (URLs look like #/main/designer). Routes are lazy import()ed; most live under the /main AppLayout parent, which carries meta.requiresAuth: true by default. /setup and /login opt out.

2. Pinia stores — inventory and the signal-counter pattern

Files live in app/stores/, kebab-case xxx-store.ts (one legacy exception: fileBrowserStore.ts). index.ts is the Pinia plugin.

The signal-counter pattern (flow-store): pendingReloadCounter + requestReload() means "re-read the graph from core". It is used after an out-of-band backend mutation (AI apply), after every undo/redo, after a save that changes edges server-side (RunFlow), and after any failed mutation (the mutation channel requests it for every refused ordered request; see §3) — the canvas never patches itself back. Canvas.loadFlow flushes pending edits once, waits for the mutation queue, re-reads if mutationGeneration() moved, and keeps viewport and selection when reloading the same flow. Canvas.vue watches the counter, not a boolean, so that two reload requests in the same tick still both fire (a boolean flag toggled twice collapses to a no-op watch). pendingLayoutResetCounter / requestLayoutReset() is the same idea for re-running auto-layout. Use this pattern for any new "something changed, someone downstream should react" signal — don't reach for a boolean.

editorStore.graphVersion is different: bumped by nodeStore.updateSettings after every successful save and by flowStore.updateHistoryState for every mutation response carrying history, it represents dirty state ("something on the canvas changed"), not "reload from the network."

3. Axios conventions — and the trailing-slash 307 trap

app/services/axios.config.ts sets axios.defaults.baseURL and withCredentials = true. A request interceptor injects Authorization: Bearer <token> unless the request carries header X-Skip-Auth-Header; a response interceptor retries once on 401 after a token refresh, else calls authService.logout(). A third pair, services/mutationChannel.ts, is installed after them (request interceptors run in reverse): it sends graph mutations one at a time in issue order, applies each response's history centrally, and requests a canvas reload for every ordered request core refused. Multi-part gestures are one FlowApi.applyOperations batch built with utils/graphOperations.ts — see flowfile_frontend/CLAUDE.md ("Graph mutations", "Undo/redo and the settings drawer").

BaseURL resolution (config/constants.ts):

export const flowfileCorebaseURL = isDesktop
  ? `http://127.0.0.1:${resolveCorePort()}/`
  : `${window.location.origin}/api/`;

Desktop's port comes from window.__FLOWFILE_PORTS__, injected by the Rust shell before any renderer script runs (see §7). The base must be absolute — the AI streaming clients do new URL(path, base), which throws on a relative base.

The rule, stated once because it costs real debugging time

A frontend axios call path must match the FastAPI route string exactly, trailing slash included. FastAPI issues an absolute 307 redirect when the slash doesn't match. Verified pairs in this codebase:

• node.api.ts posts /update_settings/ ↔ routes.py @router.post("/update_settings/")
• node.api.ts posts /node/description/ ↔ routes.py @router.post("/node/description/")
• node.api.ts posts /node/reference/ ↔ routes.py @router.post("/node/reference/")

Why this bites in production and nowhere else: two proxy layers happen to paper over a mismatch during development, so the bug reaches Docker before anyone notices. vite.config.mjs's /api proxy strips the /api prefix and its configure(proxy) hook rewrites the backend's Location header back to /api/... (replicating nginx's default proxy_redirect); nginx.conf (Docker) proxies /api/ → core without overriding Host, so nginx's own default proxy_redirect also rewrites the Location back to the external URL; and pytest's TestClient follows redirects transparently too. The upshot: a slash mismatch works in npm run dev:web, works under pytest, and only breaks in a real Docker deployment. Fix it frontend-side — make the axios path match the decorator, not the other way around. Verify via docker compose logs flowfile-core | grep " 307 " after exercising the endpoint — a 307 there on a route you expected to be a 200/201/422 is this bug.

API wrapper files: app/api/*.api.ts (one per resource: node, flow, catalog, secrets, shares, userGroups, …) are static-method classes importing the configured axios instance from ../services/axios.config. app/services/ additionally holds auth.service.ts, setup.service.ts, user.service.ts, and the SSE clients aiStreamClient.ts / aiDiffClient.ts.

4. Node UI system — resolved by naming convention, not a registry

There is no static node-component registry. Settings components are found by string-interpolating a path and globbing it with import.meta.glob — fast to extend, zero build-time safety net if you get a name wrong.

Node templates come from the backend (GET /node_list); the frontend's NodeTemplate type is app/types/flow.types.ts. app/composables/useNodes.ts fetches and caches them once per session; the palette filters prod_ready nodes when environment.ts says production.

Two independent globs point at the same component tree and must stay in sync if you ever restructure the directory:

1. app/composables/useDragAndDrop.ts — import.meta.glob("../components/nodes/node-types/elements/**/*.vue"). getComponent() builds the path elements/${camelCase(item)}/${TitleCase(item)}.vue and resolves the component rendered inside the VueFlow node itself.
2. app/components/nodes/GenericNode.vue — same glob pattern, own relative path, resolves the component for the settings drawer (defineAsyncComponent, 3000ms timeout, retries ≤3, logs console.error on a missing path — this is a runtime failure, not a build error).

There are 46 element directories / 87 .vue files under app/components/nodes/node-types/elements/ today (count drifts as nodes are added — re-run the command in Provenance to check). getComponents.ts (singular get, no s on Nodes) is unrelated — it only lazy-loads elements/manualInput/*.vue editor cells for that one node's table editor.

Trap: composables/useNodes.ts also exports a getComponent that globs ../features/designer/nodes/elements/**/*.vue — that directory does not exist. It has no live callers today but will throw "Component not found" if anyone imports it. Use the useDragAndDrop loader or the GenericNode path, never this one.

Add-a-node checklist (frontend half only)

1. Backend side (template, settings schema, add_<type>) is flowfile-node-development's job — do that first.
2. Drop the icon <item>.svg into app/features/designer/assets/icons/.
3. Create the settings component at exactly app/components/nodes/node-types/elements/<camelCase(item)>/<TitleCase(item)>.vue — TitleCase capitalizes each _-separated word and joins, e.g. text_to_rows → textToRows/TextToRows.vue. A wrong directory/filename fails silently at runtime, not at build time.
4. Follow the Filter.vue pattern: wrap content in <generic-node-settings v-model="..." @request-save="saveSettings">, destructure useNodeSettings({ nodeRef, onBeforeSave }) for saveSettings/pushNodeData/handleGenericSettingsUpdate, implement loadNodeData(nodeId) hydrating from nodeStore.getNodeData, and end with defineExpose({ loadNodeData, pushNodeData, saveSettings }) — the drawer host (NodeSettingsDrawer.vue) calls these two names by contract. Never save from loadNodeData (drawers never save on open): load-time fix-ups stay in the draft. The drawer's close saves only user edits, plus what a never-configured node shows — decided by the drawer from the loaded response's NodeData.is_setup, not from your draft. Handles that depend on settings follow the saved settings (set them on load and in onAfterSave, never on an unsaved toggle).
5. No registration file to edit — both globs above pick it up automatically since they point at the same tree.
6. prod_ready: false on the backend template hides it from the production palette but keeps it loadable in already-saved flows (the full list is cached; the filter is applied per-consumer, not server-side).

5. VueFlow canvas integration

@vue-flow/core (^1.42) + @vue-flow/minimap. Canvas.vue (see §8 — it's one of the god components) owns the useVueFlow() instance and stores it in flow-store so other components/stores can findNode/mutate handles directly (e.g. a node component rewriting its own output handles for a split-output mode).

• Node ids on the canvas are the backend's numeric node ids, as strings. data carries {id, label, component (markRaw), inputs/outputs (NodeHandle[]), nodeTemplate}.
• Handle counts come from utils/nodeHandles.ts deriveHandles, driven by template input/output counts plus dynamic_inputs/output_names. multi: true templates (union, polars_code) render one input handle that accepts many edges, not N handles.
• Groups are VueFlow type: "group" nodes (composables/useNodeGroups.ts); collapsing swaps real edges for synthetic "proxy" edges. VueFlow has no @pane-dblclick event — Canvas.vue listens for the native DOM event directly instead.
• The canvas holds no unsaved graph state: send the gesture first (one FlowApi.applyOperations when it changes several things) and change the canvas only after core accepts it. Drags and arrow-key nudges send the whole moved selection; a failed mutation reloads instead of patching back.
• The right-hand drawer (Settings/Results tabs) is a declarative registry, views/DesignerView/drawerRegistry.ts — its own comment calls it "single source of truth... adding/moving a view is a one-entry edit here." Add new tabs there, not by hand-wiring a drawer component. A tab that hosts CodeMirror must defer it until visible (gate it on an active prop derived from drawer.activeTab) — it breaks if constructed while hidden. The code dock needs no such gate: DesignerView.vue v-if-mounts the .code-dock aside only while it is shown. The code generator is not a drawer tab: it is the resizable code-dock split pane in DesignerView.vue (toggled by editorStore.showCodeGenerator), holding FlowFrame | Polars | Project | Notebook.

6. lib/desktop.ts — the sole Tauri boundary

Rule (enforced by convention, not lint): view/component code must never import @tauri-apps/* directly. Every native capability is wrapped in src/renderer/lib/desktop.ts with an explicit web-mode fallback, gated on isDesktop = typeof window !== "undefined" && !!window.__TAURI_INTERNALS__.

Never call navigator.clipboard.readText() directly in renderer code. In WKWebView (Tauri's macOS webview), that call pops the native macOS "Paste" confirmation pill on every programmatic read. Always go through desktop.readClipboardText(), which uses the clipboard-manager plugin (NSPasteboard access) and never triggers it. This is why canvas paste (useDragAndDrop.ts's createManualInputFromClipboard) routes through desktop.ts instead of calling the browser API. The general principle behind this whole module: privileged operations belong on the native (Rust) side of the boundary, invoked through one narrow, auditable seam — not sprinkled through view code as direct browser/Tauri API calls.

To add a new native capability: add the Rust command to commands.rs and list it in lib.rs's tauri::generate_handler![...] (see the current set with the generate_handler grep in Provenance) — or, for a plugin command (opener, clipboard-manager) instead of a custom Rust command, add its permission string to src-tauri/capabilities/main.json's "permissions" array (no Rust code needed, but the invoke silently fails without the grant). Either way, wrap it in desktop.ts with a web-mode fallback; never call window.__TAURI__.* or @tauri-apps/* from anywhere else.

7. Tauri shell summary — and why it's the riskiest surface in this package

Modules under src-tauri/src/: lib.rs (entry/lifecycle), sidecar/{mod.rs, readiness.rs, shutdown.rs}, commands.rs, menu.rs, oauth.rs, state.rs, env.rs, window.rs.

Boot, in order: plugins register (log, opener, process, os, clipboard-manager, window-state, updater) → setup emits services-status {status:"starting"} and sidecar::start_services spawns core+worker on a scanned free port pair (core = 63578 + k*2, worker = core + 1, k in 0..100; binaries resolve from src-tauri/binaries/ in dev or <resource_dir>/binaries/ in release, staged there by make services; each process gets FLOWFILE_MODE=electron + FLOWFILE_SUPERVISOR_PID=<shell pid> injected, the latter letting shared/parent_watcher.py self-reap if the shell itself is SIGKILLed) → readiness polls GET http://127.0.0.1:<port>/docs every 1s up to a 120s deadline (core and worker awaited concurrently; cold onedir bundles + first-launch AV scanning can be slow) → on success the main window is created programmatically in Rust (not via tauri.conf.json's static window list) so an initialization_script can inject window.__FLOWFILE_PORTS__ = Object.freeze({core, worker}) before any renderer script runs — the only place that value comes from. On readiness failure, kill_spawned does a PID-only kill, no HTTP — a failed readiness often means the port itself is unresponsive, and in the NoFreePortPair edge case the recorded ports might belong to a different running Flowfile instance, so POSTing /shutdown there could kill someone else's process.

Shutdown ladder (sidecar/shutdown.rs, best-effort + idempotent): POST http://127.0.0.1:<port>/shutdown to core AND worker in parallel (3s timeout each) → sleep 2s for natural exit → Unix killpg(SIGTERM) on the whole process group (a bare kill would orphan the worker's multiprocessing children) / Windows taskkill /T /PID → poll liveness every 100ms up to 5s → still alive → killpg(SIGKILL) / taskkill /F /T.

macOS Cmd+Q / dock-quit is a distinct code path from closing the window — it surfaces as tao's RunEvent::Exit, not RunEvent::ExitRequested. The shell's run loop matches both arms; if a future edit only handles one, the other quit path leaks sidecars silently (this has happened before).