57 lines
4.6 KiB
Markdown
57 lines
4.6 KiB
Markdown
# 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.
|
||
|