@masterteam/flowplus-workflow

FlowPlus2 — workflow design-time builder package.

This package is the design-time studio + canvas + inspector + publish flow for FlowPlus workflows. It is not a runtime. It does not own:

• Work Center inboxes (@masterteam/work-center)
• Runtime dynamic form rendering (@masterteam/forms/client-form)
• Runtime task action pages or footer actions (@masterteam/components/runtime-action)
• Process-start / task-action pages (those live in host apps + Work Center)

When admins finish designing a workflow here, end-users run it through the existing Work Center inbox + ClientForm runtime that other apps already use. FlowPlus runtime needs are tracked in docs/flowplus-runtime-integration-notes.md; no shared runtime package is modified by this package today.

Layering

• @foblex/flow is used directly as the canvas and interaction layer only, and is fully isolated inside lib/builder/canvas/. No Foblex names or types leak into contracts, domain, store, or the public API.
• FlowPlus2 owns: design-time graph state, inspector logic, validation surfacing, context mapping, builder API integration, layout persistence, publish lifecycle, optional run debugger.
• Consumes @masterteam/forms only through the optional form designer adapter token. No ClientForm runtime is imported.
• State is managed with NGXS (@masterteam/components handleApiRequest
  • LoadingStateShape), matching the rest of the masterteam packages (@masterteam/work-center, @masterteam/properties, etc.).

Strict rules

• Does not depend on @masterteam/workflow.
• Does not depend on @masterteam/structure-builder.
• Does not modify @masterteam/work-center, @masterteam/forms/client-form, @masterteam/components/runtime-action, or @masterteam/client-components. Any future runtime integration must land behind a feature flag in those packages and is captured ahead of time in docs/flowplus-runtime-integration-notes.md.
• Does not own the API base URL — the host app's HTTP interceptor pipeline is responsible for base URL, auth, language, tenant, correlation, and envelope. Endpoints are emitted as bare relative paths (workflow-definitions, workflow-definitions/123/builder, …).
• Does not own the router — the host mounts the package's standalone page components at the paths it chooses.

Integration into a host app

The package mounts inside any existing Angular app. The host already provides:

• provideHttpClient(...) with its own interceptors (auth, language, tenant…)
• provideRouter(...) with the host's existing route tree
• provideAnimationsAsync(), theming (provideMTComponents, …)
• Transloco providers
• NGXS provideStore(...) (the host registers its full APP_STATES)

You do not call provideHttpClient, provideRouter, or pass an apiBaseUrl to FlowPlus.

1. Register the NGXS state

Add FlowplusWorkflowState to the host's NGXS APP_STATES array — the same array that already lists WorkCenterState, GovernanceState, etc.:

// apps/<your-app>/src/app/store/store.config.ts
import { provideStore } from '@ngxs/store';
import { FlowplusWorkflowState } from '@masterteam/flowplus-workflow';

export const APP_STATES = [
  // ...existing host states...
  FlowplusWorkflowState,
];

export const appConfig: ApplicationConfig = {
  providers: [
    provideStore(APP_STATES, /* ...host config... */),
    // ...
  ],
};

2. (Optional) Provide a navigation config

provideFlowplusWorkflow() is a no-arg setup helper for general capability flags. If the host uses different paths from the package defaults, register a navigation config so internal links follow the host's URLs:

import {
  provideFlowplusWorkflow,
  provideFlowplusWorkflowNavigation,
} from '@masterteam/flowplus-workflow';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFlowplusWorkflow(),
    provideFlowplusWorkflowNavigation({
      toStudio:  '/flowplus/studio',
      toBuilder: ({ workflowId }) => ['/flowplus/studio', workflowId, 'builder'],
      // Optional: handle "open the matching Work Center task" from the
      // builder topbar. Host wires this into its existing Work Center route.
      openRuntimeTask: ({ requestId, stepId }) =>
        router.navigate(['/work-center/my-inbox/details', requestId, 'tasks', stepId]),
    }),
  ],
};

3. Mount the page components

The host owns routing. Import the standalone page components and place them under any path that suits the host's layout/menu/permissions:

import { Routes } from '@angular/router';
import {
  WorkflowStudioPageComponent,
  WorkflowBuilderPageComponent,
  WorkflowRunDebuggerPageComponent, // optional, admin-gated
} from '@masterteam/flowplus-workflow';

export const routes: Routes = [
  // ...host's existing routes...
  {
    path: 'flowplus/studio',
    component: WorkflowStudioPageComponent,
  },
  {
    path: 'flowplus/studio/:workflowId/builder',
    component: WorkflowBuilderPageComponent,
  },
  // Optional admin route — only mount it if the host's permission system
  // also gates it. The package marks it `data: { permission: 'CONTROL_PANEL',
  // feature: 'workflowRuntimeDebugger' }`.
  {
    path: 'flowplus/studio/:workflowId/runs/:requestId/debug',
    component: WorkflowRunDebuggerPageComponent,
    data: { permission: 'CONTROL_PANEL', feature: 'workflowRuntimeDebugger' },
  },
];

There is no built-in route for "start a process" or "open a task" — those flows already live in the host's existing Work Center + ClientForm pages.

4. (Optional) Form designer adapter

If the host has a form designer, register an adapter so the UserInput step's "Open form designer" / "Preview form" buttons open it:

import { provideFlowplusFormDesignerAdapter } from '@masterteam/flowplus-workflow';

provideFlowplusFormDesignerAdapter(MyHostFormDesignerAdapter);

If no adapter is provided, the UserInput → Form tab renders an inline "Form designer not connected in this host" notice. There is no browser alert.

5. Assets

The package ships a Tailwind v4 stylesheet at @masterteam/flowplus-workflow/assets/flowplus-workflow.css. Add it to your app's stylesheets (e.g. in angular.json styles[] or imported from the app's root SCSS).

Translations live at assets/i18n/{en,ar}.json and follow the host's Transloco scope loading convention.

What the package provides

| Surface | Description | |---|---| | Studio | Workflow list + filters + create dialog | | Builder | Foblex-backed canvas, palette, inspector tabs, problems / test-run / context bottom panel | | Debugger | Admin-only context / timeline / lineage / events view (opt-in route) | | Contracts | Strongly-typed DTOs for definitions, steps, connections, triggers, catalog, context, validation, debug | | NGXS state | FlowplusWorkflowState + FlowplusWorkflowFacade (debounced saves, optimistic CRUD with rollback, layout-isolated dirty flags) | | Adapter | FLOWPLUS_FORM_DESIGNER_ADAPTER extension point | | Navigation | provideFlowplusWorkflowNavigation(...) host-configurable |

What the package does NOT provide

| Concern | Owned by | |---|---| | Inbox / task list / claim / assign | @masterteam/work-center | | Dynamic form rendering at runtime | @masterteam/forms/client-form | | Footer / dynamic runtime actions | @masterteam/components/runtime-action | | process-form-load / process-submit | host app + Work Center runtime | | API base URL / auth / interceptors | host app | | Router / route tree | host app |

If FlowPlus eventually needs additional runtime behavior from any of those packages, see docs/flowplus-runtime-integration-notes.md for the rules (opt-in feature flag, default-OFF, owner sign-off).

Backend contract status

See docs/workflow-backend-contract-gaps.md for the canonical FE/BE alignment notes and the list of endpoints required for the next backend deliverable.

Build

pnpm --filter @masterteam/flowplus-workflow build
# or
pnpm build:fp-workflow

Test

pnpm --filter @masterteam/flowplus-workflow test