# 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.