PSA/ee/docs/plans/2026-03-29-service-request-definitions/SCRATCHPAD.md

Scratchpad — Client Portal Service Requests

• Plan slug: service-request-definitions
• Created: 2026-03-29

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also update earlier notes when a decision changes or an open question is resolved.

Decisions

• (2026-03-29) Product frame is Request Services in the portal, backed by tenant-owned service_request_definition records rather than generic ticket forms.
• (2026-03-29) Templates are shortcuts only. MSPs must be able to author brand-new definitions from scratch, and template-derived definitions are ordinary definitions after creation.
• (2026-03-29) Execution architecture is workflow-centric at the platform level, but CE ships a first-class ticket-only preset as the easy path.
• (2026-03-29) Existing billing service_catalog should remain an optional linkage target, not the primary request-definition table.
• (2026-03-29) Existing workflow form infrastructure should be reused as a rendering/input primitive where useful, but request definitions remain the primary business object.
• (2026-03-29) CE/EE separation must be physical and provider-based. CE hosts the domain model and extension contracts; EE registers richer execution/form behavior/template providers.
• (2026-03-29) MVP should target the market middle: schema-driven forms with standard fields plus conditional show/hide and requester/client defaults in EE, rather than stopping at plain text boxes.

Discoveries / Constraints

• (2026-03-29) The repo already has a workflow form registry and task inbox model under ee/packages/workflows, including schema-backed form retrieval and validation paths.
• (2026-03-29) DynamicForm exists in ee/packages/workflows/src/components/workflow/DynamicForm.tsx and already renders JSON Schema/UI Schema through RJSF, making it the natural v1 rendering foundation.
• (2026-03-29) Client portal already has a request-like surface in appointment requests with authenticated client-only server actions, request history, and optional ticket linkage in packages/client-portal/src/actions/client-portal-actions/appointmentRequestActions.ts.
• (2026-03-29) The existing service_catalog model in packages/billing/src/models/service.ts is strongly billing/commercially oriented (billing_method, rates, tax, SKU, vendor, cost, license metadata) and should not carry form/workflow lifecycle concerns.
• (2026-03-29) Existing CE/EE seams already use neutral helpers and dynamic imports, e.g. server/src/lib/features.ts#getFeatureImplementation, and enterprise-only route delegation patterns in server/src/app/api/v1/extensions/*.
• (2026-03-29) The repo also contains capability/registry style patterns in EE extension infrastructure such as ee/server/src/lib/extensions/providers.ts and ee/server/src/lib/extensions/lib/gateway-registry.ts, which support the proposed provider-based request architecture.
• (2026-03-29) The visual invoice/quote designer is AST/document oriented, not input-form oriented, so it is a poor primary authoring model for v1 service request forms.

Commands / Runbooks

• (2026-03-29) Inventory workflow form/task inbox reuse:
  • rg -n "workflow_form_definitions|workflow_task_definitions|registerFormAction|taskInboxActions|DynamicForm" ee/packages/workflows/src server/src shared/workflow/runtime
• (2026-03-29) Inventory client portal request precedents:
  • rg -n "appointment request|withAuth\\(|user_type !== 'client'" packages/client-portal/src server/src/app
• (2026-03-29) Inventory service catalog scope and coupling risk:
  • rg -n "service_catalog|service categories|billing_method|default_rate" packages/billing/src server/migrations docs/billing
• (2026-03-29) Inventory CE/EE separation seams:
  • rg -n "getFeatureImplementation|enterprise|provider|registry|capability" server packages ee --glob '!**/*.test.*'

Links / References

• Workflow form registry docs: docs/workflow/form-registry.md
• Inline forms docs: docs/workflow/inline-form-example.md
• Task inbox integration docs: docs/workflow/task-inbox-integration.md
• Billing/service catalog mental model: docs/billing/billing_for_msps_with_alga_psa.md
• Billing service catalog model: packages/billing/src/models/service.ts
• Client portal ticket actions: packages/client-portal/src/actions/client-portal-actions/client-tickets.ts
• Client portal appointment request precedent: packages/client-portal/src/actions/client-portal-actions/appointmentRequestActions.ts
• Dynamic form renderer: ee/packages/workflows/src/components/workflow/DynamicForm.tsx
• CE/EE helper seam: server/src/lib/features.ts
• EE extension capability patterns: ee/server/src/lib/extensions/providers.ts
• EE extension gateway registry seam: ee/server/src/lib/extensions/lib/gateway-registry.ts

Open Questions

• Should request history visibility be submitter-only in v1, or client-wide when the contact has broader portal permissions?
• Should CE ship starter templates, or should templates begin as EE-only packaged content?
• Should linked service_catalog items be selectable from any active service, or filtered to service-only item_kind = service rows in MVP?