Flowy

Flowy is an n8n community node and TypeScript library that translates between n8n workflow JSON and a concise workflow language for humans and AI agents.

Flowy source -> typed graph IR -> n8n workflow JSON
n8n JSON    -> typed graph IR -> Flowy source + preservation

Decompiler output is controlled by three independent choices:

| Control | Values | Purpose | |---|---|---| | syntax | semantic | raw | Choose domain constructs or exact generic node declarations. | | codeDetail | full | summary | reference | Choose how executable code and long expressions appear. | | preservation | sidecar | embedded | Keep technical reconstruction data outside or inside the source. |

The defaults are:

syntax: semantic
codeDetail: summary
preservation: sidecar

Semantic source

Common n8n behavior is represented directly:

FLOWY 1

WORKFLOW "Customer Sync" active

INPUTS "Start" {
  customerId: string,
  force: boolean
} #n1

HTTP GET {{ $json.baseUrl + "/customers/" + $json.customerId }} AS "Fetch Customer" {
  responseFormat: "json"
} #n2

IF "Found?" WHEN {{ Number($json.statusCode) === 200 }} {
  true -> "Prepare Result";
  false -> "Not Found";
} #n3

SET "Prepare Result" {
  customer: {{ $json.body }},
  synchronized: true
} #n4

Flowy emits IF, FILTER, SET, HTTP, SWITCH, CODE, LOOP, EXECUTE, INPUTS, AGGREGATE, trigger forms, Google node forms, AI node forms, and typed connection aliases where the representation is an exact inverse. Unknown community nodes use the canonical NODE form. A registered semantic node shape that cannot be represented exactly is rejected rather than silently changing representation.

Code detail

codeDetail applies to Code nodes and executable parameter values such as long HTTP bodies and Set expressions.

Full

CODE "Normalize" js <<<
const input = $input.first().json;
return [{ json: { id: Number(input.id) } }];
>>> #n2

Summary

CODE "Normalize" js SUMMARY {
  ref: "sha256:...",
  characters: 1024,
  lines: 31,
  purpose: "Normalize the input payload",
  reads: ["$input.first()", "$json.id"],
  writes: ["id"],
  functions: ["normalize"],
  signals: ["1 explicit error path"]
} #n2

Reference

CODE "Normalize" js REF "sha256:..." CHARS 1024 LINES 31 #n2

Summary and reference source is stored once in the preservation code table, keyed by SHA-256. Hash, language, character count, line count, and visible summary metadata are verified during compilation.

Preservation

Technical data needed for exact reconstruction is separated from editable workflow meaning. It includes node IDs, positions, exact versions, credential references, unknown fields, generated parameter IDs, connection-array shape, and content-addressed code.

Sidecar source ends with:

PRESERVATION SIDECAR "sha256:..."

Compilation requires the matching state object.

Embedded source ends with:

PRESERVATION EMBEDDED "sha256:..." <<<
{ ...integrity-bound state... }
>>>

Embedded preservation remains attached to semantic source; it does not force raw node syntax.

Verified roundtrip invariant

Every decompile operation immediately recompiles the generated source and compares the result with the sanitized input workflow using a stable SHA-256 hash and an exact structural diff. Decompilation fails with FLOWY_ROUNDTRIP_INVARIANT if the generated package is not an exact inverse.

Credential secret payloads are removed before hashing or preservation. Flowy retains credential references only: slot, name, ID, and n8n’s managed-reference marker.

Raw syntax

Raw syntax is an explicit diagnostic and interchange choice:

NODE "acme-nodes.custom" AS "Run" {
  operation: "execute",
  payload: {{ $json }}
} #n7

It is independent of code detail and preservation placement. Raw syntax does not embed IDs and coordinates in every node; preservation still owns technical identity.

Stable handles

Handles such as #n7 bind an editable declaration to its preserved technical identity. Renaming a declaration while retaining its handle preserves the original node ID, position, exact version, credential references, and compatible unknown fields. Unknown fields are not copied across node-type changes.

n8n node operations

The Flowy node exposes:

• Compile Flowy to n8n — accepts source and optional sidecar state.
• Decompile n8n to Flowy — accepts syntax, codeDetail, and preservation.
• Validate — validates Flowy source or an n8n workflow envelope.

Language reference

The canonical language and authoring contract are in docs/FLOWY.md. Semantic adapter rules are summarized in docs/SEMANTIC_SHORTCUTS.md.

Development

npm install
npm test
npm run lint
npm run format:check
npm run pack:check

Flowy is derived from the Apache-2.0 licensed gbarnev/nflow project. See UPSTREAM.md and THIRD_PARTY_NOTICES.md.