WP Suite Flow

Flow is a WordPress plugin for building block-based forms and workflow-driven submission flows in Gutenberg, with an optional AWS backend for durable submissions, templates, workflows, and admin automation.

This repository contains the source code and frontend modules for the free / OSS parts of the WP Suite Flow plugin.

Published npm packages used by Flow include:

• @smart-cloud/flow-core
• @smart-cloud/wpsuite-core
• (shared dependency) @smart-cloud/gatey-core

---

Documentation

You can find the plugin's continuously expanding documentation at:
https://wpsuite.io/docs/

Machine-readable resources

• AI plugin manifest: https://wpsuite.io/.well-known/flow-plugin.json
• OpenAPI spec: https://wpsuite.io/.well-known/flow-openapi.yaml

---

What Flow does

Free

Flow lets you build forms in Gutenberg and render them on the front end with a single React runtime per form.

Free mode supports:

• Gutenberg form builder with dedicated layout and field blocks
• Front-end form rendering with Mantine-based UI
• Conditional logic and validation
• Shortcode support via [smartcloud-flow-form] and [smartcloud-flow-content-root]
• Elementor widget support for embedding forms or content roots outside Gutenberg
• Direct browser submission to the endpoint URL configured for each form

In free mode, WordPress/PHP does not have to proxy the request. Forms can post directly from the browser to your own endpoint.

Pro

Pro adds backend-aware capabilities designed to work with the separately deployed WP Suite Flow Backend in your own AWS account.

Pro features include:

• submissions management in wp-admin
• email templates and workflow definitions
• backend form sync
• save draft / resume flows
• authenticated API access through Gatey
• workflow automation for emails, webhooks, status changes, and related events

Important architecture note:
Backend requests are made directly from the browser where applicable.
WordPress/PHP does not proxy these calls by default.

---

AWS Backend (optional, Pro-ready)

Flow is designed to integrate with a production backend deployed into your own AWS account.

The typical Pro setup is:

1. deploy the WP Suite Flow backend to AWS
2. register that API in Gatey
3. choose the matching protection mode for the API (IAM or COGNITO)
4. select that API in SmartCloud → Flow Settings → API Settings

This keeps WordPress as the editing and presentation layer while AWS handles durable submissions, workflow orchestration, and related backend automation.

---

Project Structure

• core/
  Shared JavaScript modules, transport helpers, runtime logic, and backend integration primitives.
  Published package: @smart-cloud/flow-core

• main/
  Base runtime JavaScript and CSS features loaded where needed on the site; build here and copy the generated assets from main/dist/ into the final plugin layout.

• admin/
  WordPress admin interface for Flow settings and backend-aware admin tooling; build here and copy the generated assets from admin/dist/ and admin/php/ into the final plugin layout.

• blocks/
  Gutenberg form builder blocks, field blocks, conditional logic UI, and front-end rendering support; build here and copy the generated assets from blocks/dist/ into the final plugin layout.

• wpsuite-main/ (in the Hub repository)
  Shared frontend bundle copied into hub-for-wpsuiteio/; its dist/ output provides the script loaded on every page to initialize WPSuite reCAPTCHA v3 when needed.

• wpsuite-admin/ (in the Hub repository)
  Shared WP Suite admin interface used across WP Suite plugins.

• wpsuite-*-vendor/ (in the Hub repository)
  Shared vendor bundles whose dist/ outputs are copied into hub-for-wpsuiteio/assets/js/ and hub-for-wpsuiteio/assets/css/.

• dist/ folders under main/, admin/, and blocks/
  Compiled and minified frontend output used by the WordPress plugin.

• Plugin PHP code and metadata (for example smartcloud-flow.php, readme.txt, composer.json) are located in the project root.

⚠️ Note:
The wpsuite-core package is not developed in this repository.
It lives in the separate Hub repository and is published on npm as @smart-cloud/wpsuite-core. Shared Hub assets such as wpsuite-admin/, wpsuite-main/, and wpsuite-*-vendor/ also live in that repository.

Source of Shared WPSuite Hub Code

The shared WordPress Hub code lives in the wpsuite-admin/, wpsuite-main/, and wpsuite-*-vendor/ directories of the Hub for WPSuite.io repository.
That repository hosts the shared administrative interface, global frontend assets, and vendor bundles used across WPSuite plugins, including Flow.

---

Installation and Build Guide

Prerequisites

• Node.js (>= 16.x)
• Yarn or npm
• PHP >= 8.1
• Composer
• Git

1) Clone the repositories

You typically want Flow and the Hub repository side-by-side so local linking and shared Hub asset packaging work cleanly:

git clone https://github.com/smartcloudsol/hub-for-wpsuiteio.git
git clone https://github.com/smartcloudsol/flow.git

Suggested structure:

/projects/
	hub-for-wpsuiteio/
		wpsuite-core/
		wpsuite-admin/
		wpsuite-main/
		wpsuite-amplify-vendor/
		wpsuite-mantine-vendor/
		wpsuite-webcrypto-vendor/
	flow/
		core/
		main/
		admin/
		blocks/

2) Install JavaScript dependencies

# Hub repo
cd hub-for-wpsuiteio/wpsuite-core
yarn install

cd ../wpsuite-admin
yarn install

cd ../wpsuite-main
yarn install

cd ../wpsuite-amplify-vendor
yarn install

cd ../wpsuite-mantine-vendor
yarn install

cd ../wpsuite-webcrypto-vendor
yarn install

# Flow repo
cd ../../flow/core
yarn install

cd ../main
yarn install

cd ../admin
yarn install

cd ../blocks
yarn install

3) Build and link shared packages

First, build and link wpsuite-core from the Hub repo:

cd ../../hub-for-wpsuiteio/wpsuite-core
yarn run build
npm link

Then build and link flow-core:

cd ../../flow/core
yarn run build
npm link @smart-cloud/wpsuite-core
npm link

If your local setup also requires Gatey shared auth/runtime integration, link the published or local @smart-cloud/gatey-core package as needed.

4) Link flow-core into the WordPress-facing modules

Inside the Flow modules that consume it:

# Inside flow/main, flow/admin, and flow/blocks
npm link @smart-cloud/flow-core
npm link @smart-cloud/wpsuite-core

If you build shared Hub assets locally, follow the same linking workflow used in the Hub repository.

5) Build frontend modules for WordPress

Each module that ships WordPress bundles should build into its own dist/ folder:

cd main
yarn run build-wp dist

cd ../admin
yarn run build-wp dist

cd ../blocks
yarn run build-wp dist

After building main/, admin/, and blocks/, copy the generated assets from each module's dist/ directory into the matching plugin directory. For admin/, copy the PHP files from admin/php/ as well.

If you build shared Hub assets locally, run yarn run build-wp dist in hub-for-wpsuiteio/wpsuite-main and hub-for-wpsuiteio/wpsuite-admin, and run yarn run build in any touched hub-for-wpsuiteio/wpsuite-*-vendor workspace before packaging.

6) Install PHP dependencies

From the root directory of Flow:

composer install --no-dev --no-scripts --optimize-autoloader --classmap-authoritative

7) Development workflow

• Rebuild core/ after shared package changes (yarn run build), and rebuild main/, admin/, or blocks/ with yarn run build-wp dist after WordPress bundle changes.
• If you changed wpsuite-core or flow-core, rebuild and re-link as needed.
• If you changed wpsuite-main, wpsuite-admin, or any wpsuite-*-vendor workspace in the Hub repo, rebuild those outputs before local testing or packaging.
• PHP changes are loaded by WordPress immediately.
• Use a local WordPress install for end-to-end testing of blocks, shortcode rendering, and admin flows.

---

Packaging for Deployment

Ensure the built assets are copied into the simplified plugin layout:

• main/dist/* → main/
• blocks/dist/* → blocks/
• admin/php/* and admin/dist/* → admin/

If you rebuild the shared Hub assets in the separate Hub repository, copy the following outputs into the plugin's hub-for-wpsuiteio/ directory according to that repository's instructions:

• wpsuite-main/dist/* → hub-for-wpsuiteio/
• wpsuite-admin/php/* and wpsuite-admin/dist/* → hub-for-wpsuiteio/
• wpsuite-*-vendor/dist/*.js → hub-for-wpsuiteio/assets/js/
• wpsuite-*-vendor/dist/*.css → hub-for-wpsuiteio/assets/css/

The wpsuite-main/dist/ bundle provides the script that loads on every page and initializes the reCAPTCHA v3 flow used by WPSuite plugins whenever it is needed.

Once the structure matches the layout above, create the distributable ZIP:

git archive --format zip -o smartcloud-flow.zip HEAD

This uses rules defined in .gitattributes to include only required built assets and production PHP code.

---

External Services

Depending on configuration and edition, Flow may interact with:

• Google reCAPTCHA v3 (optional): browser requests to Google to retrieve bot-protection tokens.
• Customer-configured submission endpoints: browser requests sent directly to the form endpoint URL you configure.
• WP Suite Flow Backend (optional, Pro): browser requests to the AWS-hosted backend deployed in the customer's AWS account.
• Amazon Cognito (optional): authentication flows when protected APIs use Cognito.
• WPSuite platform services (optional): workspace linking, licensing, and shared WP Suite admin/platform capabilities.

---

License

MIT License

---

If you encounter issues or want to contribute, feel free to open an issue or pull request.