FlowDelta Documentation

FlowDelta Documentation

Complete guides for using, understanding, and extending FlowDelta.

Quick start

New to the project? Start here:

1. Getting Started — Set up locally, run tests, understand the codebase structure
2. Salesforce Flow Primer — What is a .flow-meta.xml file and how is it structured?
3. Architecture — The pipeline: parser → model → diff → render

Using FlowDelta

• CLI usage — File, git, and Salesforce org modes, command-line options, output formats
• Shared metadata/Git IO — Local/Git reader and discovery contracts used by both CLIs
• CI Integration — Running in GitLab/GitHub pipelines, MR/PR reporting, sticky comments, private-repo artifact viewing

Understanding the system

• Data Model Reference — Core types (GraphModel, GraphNode, FlowDiff, etc.) and how they flow through the pipeline
• Salesforce Flow XML Primer — XML structure, element types, connectors, and how FlowDelta parses them
• Architecture — Module responsibilities, canonicalization rules, invariants that must hold
• Rendering — Interactive HTML features, section schemas, layout strategy, side panel organization
• FlexiPageDelta — Semantic diffs and wireframes for Salesforce Lightning pages

Extending and customizing

• Section Schema Authoring — How to define semantic property grouping for new or modified node types
• Extending for New Node Types — Adding support for new Salesforce Flow elements
• Publishing — Build, package, and npm release process

Development

• Testing — Test layout, test fixtures, how to add new test cases
• Getting Started — Local setup, running tests, common workflows
• Debugging & Troubleshooting — Parse errors, unexpected diffs, layout issues, and troubleshooting strategies
• Vendoring Policy — The Apache-2.0 parser, provenance, do-not-edit rules, licensing
• Documentation site — Local preview, link authoring, and release publication

Navigation by task

I want to…

Compare flows locally or from Salesforce → Getting Started → CLI usage

Set up CI reporting in GitLab or GitHub → CI Integration + examples/gitlab-ci.yml / examples/github-actions.yml

Understand why a diff looks wrong → Debugging & Troubleshooting → Data Model Reference

Add support for a new Salesforce element type → Extending for New Node Types → Section Schema Authoring

Improve the visual rendering of changes → Section Schema Authoring → Rendering

Understand the code architecture → Architecture → Data Model Reference → Relevant module

Write a test for a new scenario → Testing → Debugging & Troubleshooting

Release a new version → Publishing

Build or update the documentation site → Documentation site

Module reference

Module	Doc
src/parser/	Vendoring Policy (read-only, Apache-2.0)
src/io/	Shared metadata/Git IO, CLI usage
src/model/	Data Model Reference, Architecture
src/diff/	Architecture
src/render/	Rendering, Section Schema Authoring
src/ci/	CI Integration
test/	Testing, Debugging & Troubleshooting

Key concepts

Canonicalization — Normalization of properties before diffing (strips coordinates, connectors, sorts unordered arrays). See Architecture.

Section schema — Type-specific configuration for rendering property changes as semantic sections (e.g., “Outcomes” for decisions). See Section Schema Authoring.

GraphModel — Normalized representation after parsing: nodes + edges, with coordinates and connectors stripped. See Data Model Reference.

FlowDiff — The semantic diff output: added/deleted/modified nodes and edges with per-property changes. See Data Model Reference.

Fixture — A pair of before/after flows used to test and verify behavior. See Testing.

Vendored parser — The Google Flow Lens parser (Apache-2.0), imported verbatim and not edited. See Vendoring Policy.

Documentation map

docs/
  README.md (this file)
  getting-started.md       — Local setup & first run
  data-model.md            — Type reference & pipeline overview
  salesforce-flow-primer.md — XML structure & element types
  architecture.md          — Pipeline, modules, invariants
  render.md                — HTML rendering & interactive features
  section-schemas.md       — Semantic property organization
  extending-node-types.md  — Adding new element type support
  cli.md                   — Command-line interface
  metadata-io.md           — Shared metadata and Git input boundary
  ci.md                    — GitLab + GitHub CI integration
  flexipage.md             — Lightning page semantic diff and wireframe pipeline
  testing.md               — Test layout & fixture authoring
  docs-site.md             — Documentation authoring, local build, and publication
  publishing.md            — Build & npm release
  vendoring.md             — Parser policy & licensing
  debugging.md             — Troubleshooting strategies

Conventions

• File paths are relative to the project root: src/cli.ts, test/semantic-diff.test.ts
• Code examples use npm and npm run scripts; see package.json
• Terminals show bash/sh syntax; Windows users should use PowerShell or Git Bash
• Links to source code assume you’ve cloned the repo and have it open

Contributing

See CONTRIBUTING.md for code style, PR expectations, and the development workflow.

License

FlowDelta code is MIT. The vendored parser is Apache-2.0. See LICENSE and LICENSE-APACHE.