Files
HiveGrid-Wireframes/hivegrid-cloud/docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md
T

13 KiB

Knowledge Base, Widgets, Workflow Engine, and Public Marketing Decision Report

Decision

Decision: extract-plugin for Knowledge Base, Widgets, and Workflow Engine.

Decision: remove-from-core for Public Marketing remnants, including Public Marketing, Blog, Changelog, and marketing-chatbot surfaces.

D009 classifies Knowledge Base, Widgets, and Workflow Engine as optional plugin candidates, not Boilerplate Core and not immediate deletion targets. D009 also classifies remaining Public Marketing/Blog/Changelog/marketing-chatbot surfaces as removal candidates because marketing content and unauthenticated marketing automation conflict with the target minimal boilerplate core. This report is the canonical Feature Decision/S05 lifecycle source for R009 while supporting R001, R002, and R003 through a deterministic, sequential decision pass.

No runtime routes, schema, package dependencies, API handlers, sidebar registrations, workers, queues, or data records are changed in this slice. This slice records the decision contract only so later implementation slices can extract plugins or remove marketing remnants atomically after their route, schema, API, dependency, sidebar, public-data, and worker boundaries are audited.

Scope

The scoped feature groups are Knowledge Base, Widgets, Workflow Engine, and Public Marketing remnants. The canonical action tokens are:

  • Knowledge Base: extract-plugin.
  • Widgets: extract-plugin.
  • Workflow Engine: extract-plugin.
  • Public Marketing remnants: remove-from-core.

The scoped documentation and manifest sources are docs/feature-inventory.md, docs/feature-manifests/plugin-candidates.json, and docs/feature-manifests/remove-candidates.json. They must keep Knowledge Base, Widgets, and Workflow Engine in the plugin-candidate boundary and keep Public Marketing/Blog/Changelog/marketing-chatbot in the removal-candidate boundary. This report does not reclassify unrelated features and does not authorize runtime pruning during Feature Decision/S05.

Current Code Surfaces

Concrete surfaces that later work must audit before changing runtime behavior:

  • Knowledge Base module: apps/web/app/modules/knowledgeBase.
  • Knowledge Base admin routes: apps/web/app/routes/admin/knowledge-base*.
  • Knowledge Base public docs routes: apps/web/app/routes/docs/*.
  • Knowledge Base plugin-disabled help route tree: apps/web/app/routes/help/*.
  • Knowledge Base schema: prisma/schema/knowledgeBase.prisma.
  • Widgets module: apps/web/app/modules/widgets.
  • Widgets tenant routes: apps/web/app/routes/app.$tenant/__widgets/*.
  • Widgets API surface: apps/api/src/app.ts.
  • Widgets package DB helper: packages/db/src/widgets.server.ts.
  • Workflow schema: prisma/schema/workflows.prisma.
  • Workflow Engine module: apps/web/app/modules/workflowEngine.
  • Workflow admin routes: apps/web/app/routes/admin/__workflows/*.
  • Workflow tenant routes: apps/web/app/routes/app.$tenant/__workflows/*.
  • Workflow API routes: apps/web/app/routes/internal/api/__workflows/*.
  • Blog, changelog, and brand route surfaces were removed during pruning and remain historical evidence only.
  • Public entity route: apps/web/app/routes/public/$entity.$id.tsx.
  • Marketing chatbot route and tool surfaces were removed during pruning and remain historical evidence only.

Knowledge Base Boundary

Knowledge Base is a support/docs product surface and is classified by D009 as extract-plugin. It is useful for products that need public help centers, localized articles, and support content, but it is not required for the minimal boilerplate core.

Later extraction must account for apps/web/app/modules/knowledgeBase, apps/web/app/routes/docs/*, apps/web/app/routes/admin/knowledge-base*, apps/web/app/routes/help/*, and prisma/schema/knowledgeBase.prisma together. The public docs routes create a public-data boundary: article content may be intentionally public, but draft state, tenant ownership, author metadata, internal support content, localized variants, and any user-generated or operational metadata must not become publicly exposed during extraction.

Knowledge Base must remain a plugin candidate, not a Public Marketing removal candidate, even if some seed or fake article content is later removed as source-product copy. Public help content and admin knowledge-base management need their own plugin-owned route, schema, sidebar, and data-retention plan before code moves or schema is pruned.

Widgets Boundary

Widgets are classified by D009 as extract-plugin. Embedded widgets are product-specific because they expose tenant-configured embed behavior, public or semi-public API access, and integration expectations that vary by product.

Later extraction must audit apps/web/app/modules/widgets, apps/web/app/routes/app.$tenant/__widgets/*, apps/api/src/app.ts, and packages/db/src/widgets.server.ts together. The API and package DB surfaces mean Widgets are not only a UI module: API handlers, route parameters, widget identifiers, tenant ownership, and ORM-safe data access must remain aligned.

Widgets include a public/API boundary because embedded widget IDs and API reads may be exposed outside the authenticated tenant shell. Later work must validate and normalize widget identifiers, keep tenant ownership checks explicit, preserve parameterized/ORM-safe filters, and avoid exposing tenant-private configuration, PII, or internal widget records through public embed endpoints.

Workflow Engine Boundary

Workflow Engine is classified by D009 as extract-plugin. It is a powerful automation surface, but its dependency, schema, API, and possible worker/queue behavior make it too complex and product-specific for the minimal boilerplate core.

Later extraction must audit apps/web/app/modules/workflowEngine, apps/web/app/routes/admin/__workflows/*, apps/web/app/routes/app.$tenant/__workflows/*, apps/web/app/routes/internal/api/__workflows/*, and prisma/schema/workflows.prisma together. Workflow route ownership spans admin, tenant app, and API surfaces, so partial extraction would leave broken automation entry points or orphaned schema.

Workflow execution now has an explicit worker/outbox boundary in the current codebase: workflow event producers publish through the outbox, the worker-general group can route outbox.workflow, and the worker-native trigger runner owns idempotent execution startup. Later extraction must preserve or replace that boundary and define whether workflow definitions, runs, triggers, logs, retries, external event subscriptions, and package dependencies move into a worker-backed plugin, remain disabled unless the plugin is installed, or are removed only after data retention and audit requirements are satisfied.

Public Marketing Removal Boundary

Public Marketing remnants are classified by D009 as remove-from-core. Blog, brand, playground/debug, marketing-chatbot, and public row sharing at apps/web/app/routes/public/$entity.$id.tsx have been pruned and remain historical evidence only. Future scans should treat any reintroduced unauthenticated marketing/public row surface as a regression.

These surfaces are removal candidates, not plugin candidates, because marketing sites, blog/changelog content, public entity marketing pages, and unauthenticated marketing chatbot behavior belong outside the default boilerplate. Later pruning must preserve only neutral Core public pages that are required for auth, legal, billing, or app shell behavior.

Marketing chatbot removal must be handled carefully because it touches AI/chatbot routes and tools. The remove-from-core action applies only to the marketing chatbot API route and marketing-specific tool implementations named in this report; it does not reclassify the broader AI, chatbot, prompt builder, or MCP plugin-candidate surfaces.

Schema and Data Impact

No schema or data changes occur in Feature Decision/S05. Later Knowledge Base extraction must account for prisma/schema/knowledgeBase.prisma, public help article visibility, localization, draft/published state, tenant ownership, authoring metadata, and any fake/source-product article content that should be removed separately from plugin extraction.

Later Widgets extraction must preserve the data contract used by packages/db/src/widgets.server.ts, tenant-owned widget configuration, API-visible widget identifiers, public embed access, and any PII or tenant-private fields that must not leak through API handlers. Widget data should be migrated, exported, retained, or disabled through a plugin-owned lifecycle instead of silently deleted.

Later Workflow Engine extraction must include a schema/data plan for prisma/schema/workflows.prisma, including definitions, triggers, execution state, logs, retries, external subscriptions, and tenant ownership. Later Public Marketing cleanup must keep blog/changelog content, public entity pages, marketing-chatbot prompts/tools, source-product copy, and related fake data outside Core without affecting retained Core data.

Sidebar API and Package Dependency Impact

No sidebar entries, API handlers, or package dependencies are changed in this slice. Later Knowledge Base extraction must update admin/help navigation only through an explicit plugin enablement or routing boundary, while keeping Core navigation free of support-docs product assumptions.

Later Widgets extraction must handle tenant sidebar visibility, apps/api/src/app.ts widget endpoints, packages/db/src/widgets.server.ts, widget route parameters, and package ownership together. Removing or moving only the UI routes would leave API/package surfaces behind; removing only API support would break embedded widgets still reachable from tenant routes.

Later Workflow Engine extraction must audit package dependencies such as workflow graph/automation libraries together with apps/web/app/modules/workflowEngine, workflow schema, admin/tenant/API routes, and any worker/queue runtime. Later Public Marketing removal may allow marketing-only chatbot, blog, changelog, visual editor, or marketing asset dependencies to be pruned, but only after consumers are proven gone.

Execution Plan

  1. Land this D009 report and align docs/feature-inventory.md, docs/feature-manifests/plugin-candidates.json, and docs/feature-manifests/remove-candidates.json so human-readable and machine-readable sources point to the same canonical decision.
  2. Add a static verifier that checks required headings, exact action tokens, D009/R001/R002/R003/R009 citations, required path references, manifest alignment, placeholder-free content, and absence of runtime-change instructions in this documentation slice.
  3. Audit Knowledge Base routes, module code, schema, admin/sidebar exposure, public help visibility, localization, source-product/fake content, and public-data boundaries before extraction.
  4. Audit Widgets tenant routes, API handlers, packages/db/src/widgets.server.ts, identifier validation, tenant ownership, public embed behavior, package dependencies, and sidebar visibility before extraction.
  5. Audit Workflow Engine admin/tenant/API routes, schema, dependency graph, trigger/run/log data, worker/queue expectations, retries, and API behavior before extraction.
  6. Keep apps/web/app/routes/public/$entity.$id.tsx and removed Blog/Brand/debug/playground/chatbot paths as historical D009 evidence rather than active code areas; any reintroduction needs an explicit plugin or product decision.
  7. Implement runtime extraction or removal only in later implementation slices after the verifier and audits prove route, schema, API, package dependency, sidebar, public-data, and worker boundaries can change atomically.

Verification Plan

The Feature Decision/S05 verifier must fail with explicit diagnostics when required sections are missing, exact action tokens are absent, D009 or R001/R002/R003/R009 citations are missing, required paths drift, placeholders appear, manifest classification no longer matches the report, inventory references drift, Public Marketing/Blog/Changelog/marketing-chatbot are incorrectly moved to plugin candidates, or the report suggests runtime code changes in this slice.

Task-level verification for this report is static: the file must be non-empty, contain no unresolved placeholder markers, cite D009, and contain the exact action tokens extract-plugin and remove-from-core. Slice-level verification later runs scripts/verify-kb-widgets-workflow-marketing-decision-report.mjs and focused Vitest drift tests without browser, Playwright, Cypress, or other E2E execution.

Risks

The main risk is partial implementation after this decision pass: extracting Knowledge Base without public help/data boundaries, moving Widgets UI without API and package DB ownership, changing Workflow Engine routes without schema and worker/queue planning, or removing marketing chatbot code while leaving unauthenticated public behavior reachable elsewhere.

A second risk is classification drift. Knowledge Base, Widgets, and Workflow Engine must remain extract-plugin candidates unless D009 is superseded, while Public Marketing/Blog/Changelog/marketing-chatbot must remain remove-from-core candidates rather than being packaged as default plugins. Downstream agents must treat this report as the decision boundary and verify documentation/manifest alignment before any runtime code changes.