PSA/ee/docs/plans/2026-01-29-workflows-ee-folder-structure/PRD.md

PRD: Move Workflow EE UI into ee/server Folder Structure

Problem Statement

The Workflow UI currently uses “feature package” entrypoints under packages/workflows/src/{oss,ee} and relies on build-time aliasing of @alga-psa/workflows/entry to select the correct implementation.

In practice, Enterprise builds can still ship the OSS/CE stub UI (“Enterprise Feature / Please upgrade…”) even when:

• The app is deployed with EE images, and
• Runtime env vars indicate Enterprise (EDITION=enterprise, NEXT_PUBLIC_EDITION=enterprise).

We observed this in the HV dev2 environment: the deployed .next output contained the OSS/CE stub strings (historically under packages/workflows/src/oss/entry.tsx), indicating a “hybrid” build.

Root cause class: TS path-based resolution (Next’s JsConfigPathsPlugin) can override/short-circuit webpack aliasing, meaning the EE/OSS selection is not consistently enforced at build time.

This is confusing operationally and erodes trust: users see EE-only gating dialogs even in Enterprise deployments.

Status (as of 2026-01-29)

This plan is implemented in the current repo state.

Implemented (in repo today)

• The authoritative EE entry is ee/server/src/workflows/entry.tsx and exports DnDFlow.
• The authoritative CE stub entry is server/src/empty/workflows/entry.tsx and exports DnDFlow with the legacy stub text.
• server/next.config.mjs aliases @alga-psa/workflows/entry deterministically for both webpack + turbopack.
• server/tsconfig.json and ee/server/tsconfig.json no longer map @alga-psa/workflows/entry.
• Typings for @alga-psa/workflows/entry are provided via server/src/types/external-modules.d.ts.
• CI/build guards exist to prevent hybrid EE builds and to validate CE builds:
  • scripts/guard-workflows-entry-edition-selection.mjs
  • scripts/guard-ee-workflows-next-build.mjs
  • scripts/guard-ce-workflows-next-build.mjs
  • .github/workflows/workflows-ee-build-guard.yml
• A UI smoke test exists: ee/server/src/__tests__/integration/workflows-ee-entry-smoke.playwright.test.ts.

Not yet implemented (still outstanding)

None. Remaining work is optional cleanup (e.g. removing any empty legacy directories under packages/workflows/src/ee/** if desired).

User Value

• Enterprise deployments reliably load the real Workflow UI (designer, toggles, run studio).
• CE deployments reliably load stubs (or hide the feature), without “hybrid” behavior.
• A clearer code layout: EE-only UI lives in ee/server/src/**, aligning with other EE feature wiring.
• Fewer build-time footguns: no reliance on TS “paths” for runtime selection.

Goals

1. Relocate the Workflow UI EE implementation from packages/workflows/src/ee/** into the EE tree under ee/server/src/**.
2. Ensure @alga-psa/workflows/entry resolves deterministically to:
   • ee/server/src/** in EE builds
   • server/src/empty/** (or other CE stub) in CE builds
3. Remove or neutralize TS path mappings that can cause the OSS stub to be bundled in EE.
4. Keep the import surface stable for app code (@alga-psa/workflows/entry, @alga-psa/workflows/components/*) to avoid widespread refactors.
5. Add regression tests that detect “OSS stub shipped in EE build”.

Non-Goals

• Rewriting the workflow engine/runtime or Temporal workflows.
• Changing licensing/entitlement policy (still EE-only where intended).
• Migrating all workflow-related shared code into ee/ (schemas/types/shared runtime can remain in packages/workflows).
• UI redesign.

Background / Current Architecture

Current entrypoint selection

• packages/workflows/src/components/WorkflowComponentLoader.ts dynamically imports @alga-psa/workflows/entry.
• server/next.config.mjs attempts to alias @alga-psa/workflows/entry to:
  • EE: packages/workflows/src/ee/entry.tsx
  • OSS/CE: packages/workflows/src/oss/entry.tsx
• server/tsconfig.json currently maps @alga-psa/workflows/entry to packages/workflows/src/entry (which re-exports the OSS stub).

Why this breaks

Next’s TS/JS config path resolver can resolve @alga-psa/workflows/entry via tsconfig paths before webpack aliasing, causing the OSS stub to end up in the EE bundle (hybrid build).

Proposed Architecture

Code placement

• EE Workflow UI lives under ee/server/src/** (new home), e.g.:
  • ee/server/src/workflows/entry.tsx (or ee/server/src/components/workflows/entry.tsx)
  • ee/server/src/workflows/** for designer subcomponents
• CE/OSS stub lives under server/src/empty/**, e.g.:
  • server/src/empty/workflows/entry.tsx
  • (or reuse existing server/src/empty/components/flow/DnDFlow.tsx with a thin entry wrapper)

Build-time wiring (authoritative)

• In server/next.config.mjs, alias @alga-psa/workflows/entry directly to these concrete files.
• Ensure both webpack and turbopack aliasing cover it.

TypeScript wiring (non-authoritative)

• Remove tsconfig paths mapping for @alga-psa/workflows/entry (and any similar “runtime-selected” specifiers).
• Provide typings via:
  • server/src/types/external-modules.d.ts (or a dedicated workflows-entry.d.ts) declaring DnDFlow and related exports.

This makes TS happy without allowing TS paths to affect runtime bundling.

Migration / Rollout Plan

1. Introduce new EE entry file in ee/server/src/** that exports the expected DnDFlow named export.
2. Introduce new CE stub entry file in server/src/empty/** matching the export shape.
3. Update server/next.config.mjs to point @alga-psa/workflows/entry at the new locations for both webpack + turbopack.
4. Remove tsconfig paths entry for @alga-psa/workflows/entry (and update any dependent tsconfigs, e.g. ee/server/tsconfig.json).
5. Remove legacy packages/workflows/src/{ee,oss} entrypoints rather than keeping re-export shims, to prevent any accidental “hybrid” resolution paths in future builds.
6. Add a CI guard for EE builds:
   • After next build with EE env, grep .next/server for known OSS stub strings and fail if present.
7. Deploy to HV dev2 and validate:
   • Workflows page loads real designer UI
   • No EE-only gating dialog appears in EE deployments

Risks

• Moving UI code may introduce import boundary violations (feature-to-feature lint rules).
• ee/server/src code may depend on packages not present in some build contexts; require careful aliasing and transpilePackages.
• Turbopack vs webpack differences: ensure both codepaths are wired identically.
• Any other “runtime-selected” entrypoints could have similar TS-path precedence issues; scope creep risk.

Open Questions (needs user confirmation)

Resolved (2026-01-29):

1. All workflow UI will be moved into ee/server/src/** (designer, run studio, and related workflow surfaces).
2. CE behavior will be a stub message indicating the feature requires Enterprise.
3. Scope is workflows-only (do not expand to other runtime-selected entrypoints).

Acceptance Criteria / Definition of Done

• In an EE next build output, .next/server/** does not contain strings from the OSS workflow stub entry.
• In HV dev2 (or equivalent), the deployed EE image loads the real workflow designer UI.
• CE builds still compile and behave as expected (stub/hide), with no EE-only code shipped unintentionally.
• Added CI regression check(s) prevent hybrid workflow builds going forward.