Architecture Overview

This page explains how FlowDrop is structured internally, so you can make informed decisions about what to import, how to integrate, and where to extend.

High-Level Architecture

FlowDrop is a frontend library that communicates with your backend via REST.

Module Structure

FlowDrop is tree-shakable. Each sub-module has different dependencies and bundle cost:

Module	What it provides	Heavy deps
@flowdrop/flowdrop/core	Types, utilities, auth providers, config helpers	None
@flowdrop/flowdrop/editor	WorkflowEditor, mount functions, node components	@xyflow/svelte
@flowdrop/flowdrop/form	SchemaForm, field components	None
@flowdrop/flowdrop/form/code	Code & template editors	CodeMirror (~300KB)
@flowdrop/flowdrop/form/markdown	Markdown editor	CodeMirror
@flowdrop/flowdrop/display	MarkdownDisplay	marked
@flowdrop/flowdrop/playground	Playground, chat, interrupts	Editor + Form
@flowdrop/flowdrop/settings	Settings panel, theme toggle	Form
@flowdrop/flowdrop/styles	CSS design tokens	None
@flowdrop/flowdrop	Full bundle (everything)	All of the above

Dependency chain:

Import from the most specific module possible to minimize bundle size.

Component Hierarchy

When you mount mountFlowDropApp(), this is the component tree:

• DirectoryApp

  • DirectoryNavbar

    • Logo
    • WorkflowName (editable)
    • Save / Export buttons
    • Custom NavbarActions
    • ThemeToggle / Settings
  • DirectoryNodeSidebar

    • Search
    • DirectoryCategoryGroups

      • NodeCards (draggable)
  • DirectoryWorkflowEditor (@xyflow/svelte canvas)

    • DirectoryNodes (WorkflowNode, SimpleNode, GatewayNode, etc.)

      • Ports (input/output handles)
    • Edges (styled by category)
    • ConnectionLine
  • DirectoryConfigPanel (right side, on node click)

    • NodeHeader (name, type, icon)
    • DirectorySchemaForm (generated from configSchema)

      • FormFields (text, select, code, template, etc.)
  • ToastContainer

mountWorkflowEditor() mounts just the canvas — no navbar, no sidebar.

Stores

FlowDrop uses Svelte 5 runes for state management. Stores are module-level singletons:

Store	Purpose	Key state
workflowStore	Central workflow state	nodes, edges, metadata, isDirty
historyStore	Undo/redo	past states, future states, canUndo/canRedo
settingsStore	User preferences	theme, editor behavior, UI config
playgroundStore	Playground sessions	sessions, messages, isExecuting
interruptStore	Human-in-the-loop	pending/resolved interrupts
categoriesStore	Node categories	category definitions, colors
portCoordinateStore	Handle positions	port coordinates for edge rendering

Single Instance

FlowDrop uses module-level singleton stores. Only one FlowDrop editor can exist per page. Mounting a second instance will share state with the first.

Services

Services handle communication and side effects:

Service	Purpose
API client	HTTP requests to your backend (nodes, workflows, execution)
Draft storage	Auto-save to localStorage
Toast service	Success/error/loading notifications
Dynamic schema	Fetch config schemas from API at runtime
Playground service	Manage sessions, poll for messages
Interrupt service	Submit interrupt resolutions
History service	Track and replay state changes
Settings service	Load/save preferences (localStorage + API)

Data Flow

Here’s what happens when a user makes a change:

When the user saves:

Registry System

FlowDrop has two registries for extending the editor:

Node Component Registry

Register custom Svelte components for new node types:

import { registerCustomNode } from '@flowdrop/flowdrop/editor';
registerCustomNode('my-custom-node', MyNodeComponent);

Field Component Registry

Register custom form fields for config schemas:

import { registerFieldComponent } from '@flowdrop/flowdrop/form';
registerFieldComponent(matcher, MyFieldComponent, { priority: 10 });

Both registries are singletons that persist for the page lifetime. Register before or after mounting.

Next Steps

• What is a Workflow? — the mental model
• Quick Start — mount FlowDrop in your app
• Backend Implementation — build the API FlowDrop expects
• Event System — hook into every lifecycle event