Assist_Design/docs/_archive/migration/MIGRATION-STATUS-UPDATE.md

Migration Status Update (October 2025)

The checklist in this document previously claimed a full migration. That was premature. Treat the legacy @customer-portal/contracts, @customer-portal/schemas, and @customer-portal/integrations-* packages as active until the tasks below are completed.

Current Snapshot

• Provider exports are live: Each domain barrel re-exports a Providers namespace (packages/domain/orders/index.ts, packages/domain/billing/index.ts). The subpath mappings in packages/domain/package.json enable imports such as import { Providers } from "@customer-portal/domain/orders" and import { transformWhmcsInvoice } from "@customer-portal/domain/billing/providers/whmcs".
• Apps still lean on legacy packages: BFF services and controllers continue to import contracts, schemas, and mappers from @customer-portal/contracts, @customer-portal/schemas, and @customer-portal/integrations-*. Examples include apps/bff/src/modules/orders/services/order-whmcs-mapper.service.ts and apps/bff/src/integrations/freebit/services/freebit-operations.service.ts.
• Legacy domain tree still mounted: Types and schemas under packages/domain/src/** are still referenced by the apps. That package cannot be removed yet.
• Request schemas are misplaced: Freebit and WHMCS request schemas remain under packages/schemas/src/integrations/** instead of living alongside their providers.
• Tooling and docs lag behind: Lint rules, Dockerfiles, CI scripts, and tsconfig path aliases still reference the old packages. Documentation (including this file) had not been updated to reflect the real status.
• Missing domain coverage: Auth flows, Salesforce entities, and common primitives (address, user profile, etc.) have not been migrated into dedicated packages/domain/* modules.

What’s Done

• Domain package exposes the new provider-aware barrels and subpath exports.
• Provider mapper logic has been lifted into packages/domain/<domain>/providers/** for the supported vendors.
• New import surface has been verified locally (e.g. Providers.Whmcs, Providers.Freebit).

Gaps to Close Before Calling the Migration “Complete”

1. Audit & update imports

   • Replace @customer-portal/contracts/*, @customer-portal/schemas/*, and @customer-portal/integrations-* usages across BFF, portal, and integration code with the new domain paths (@customer-portal/domain/<domain> and Providers.<Vendor>).
   • Remove fallbacks to @customer-portal/domain root barrels in favour of explicit subpaths.

2. Relocate provider request schemas

   • Move Freebit and WHMCS request validators into the relevant provider directories under packages/domain/<domain>/providers/<provider>.
   • Update service call sites (e.g. freebit-operations.service.ts) to import from the new locations.

3. Split out remaining domains

   • Introduce an auth/ domain for authentication types and schemas currently stored in packages/domain/src/**.
   • Add a salesforce/ (or common/salesforce.ts) module for Salesforce entities used by integrations and configuration files.
   • Consolidate shared primitives in packages/domain/common/ (address, identifiers, etc.).

4. Retire the legacy domain package

   • Once the apps reference only packages/domain/<domain>, delete packages/domain/src/** and purge related tsconfig and ESLint paths.
   • Update lint rules (e.g. eslint.config.mjs) to forbid importing from the legacy packages.

5. Deprecate old packages

   • After consumers migrate, archive or replace @customer-portal/contracts, @customer-portal/schemas, and @customer-portal/integrations-* with thin re-exports (or remove them entirely if unused).
   • Ensure Docker builds, CI pipelines, and documentation stop referencing these packages.

6. Portal alignment & verification

   • Apply the same import sweep to the portal (apps/portal/**).
   • Run full type-checks (pnpm --filter @customer-portal/bff type-check, etc.) and document remaining issues.

Suggested Sequence

1. Codemod imports across BFF and portal to point at the new domain subpaths and provider namespaces.
2. Move request schemas for Freebit and WHMCS into their provider folders; update services accordingly.
3. Add new domain modules for auth, Salesforce, and shared primitives; backfill exports.
4. Remove legacy references from configs, ESLint, and tooling.
5. Retire packages & update docs once all code points at @customer-portal/domain/*.

Track progress by running targeted type-checks and lint rules after each phase, and update this document as milestones are hit.