Assist_Design/docs/HONEST-MIGRATION-AUDIT.md

Honest Migration Audit - Current State

Date: October 3, 2025
Auditor: AI Assistant
Purpose: Reality check before proceeding

---

📊 Actual Numbers

BFF Status

• Files importing from bare @customer-portal/domain: 39 files (48 import statements)
• Files importing from old packages: 3 files
  • @customer-portal/contracts/* - 2 files
  • @customer-portal/schemas/* - minimal
  • @customer-portal/integrations-freebit/utils - 1 file

Portal Status

• Files importing any package: 68 files
• Migration status: NOT STARTED

Infrastructure Status

• ✅ Domain structure exists and compiles
• ✅ Provider namespaces work (Providers.Whmcs.*)
• ❌ Request schemas duplicated (new ones created but old ones still referenced)
• ❌ Legacy packages/domain/src/** still active
• ❌ Old packages still functional

---

🎯 What I Actually Accomplished

Completed (True)

1. Created complete domain structure - 8 domains with contracts, schemas, providers
2. Migrated 12 integration service files - Updated to use new imports
3. Established provider pattern - Working namespace exports
4. Built domain package - Compiles successfully
5. Created request schemas - New files in packages/domain/*/providers/*/requests.ts

NOT Completed (Reality)

1. Did NOT remove old request schema files - They still exist in packages/schemas/src/integrations/**
2. Did NOT update all BFF files - 39 files still use bare @customer-portal/domain import
3. Did NOT create auth domain - Auth types still missing
4. Did NOT create salesforce domain - Salesforce types still missing
5. Did NOT update Portal - 68 files need attention
6. Did NOT remove legacy packages - All old code still present

---

🔧 Systematic Migration Plan (No Shortcuts)

Phase 1: Fix BFF Bare Imports (39 files)

Estimated time: 45 minutes

Replace all bare @customer-portal/domain imports with specific domain paths:

// ❌ WRONG
import { Invoice, Subscription } from "@customer-portal/domain";

// ✅ CORRECT
import { Invoice } from "@customer-portal/domain/billing";
import { Subscription } from "@customer-portal/domain/subscriptions";

Files to update:

• apps/bff/src/integrations/whmcs/*.service.ts (10+ files)
• apps/bff/src/modules/auth/**/*.ts (15+ files)
• apps/bff/src/modules/catalog/**/*.ts (5 files)
• apps/bff/src/modules/invoices/**/*.ts (3 files)
• apps/bff/src/modules/orders/**/*.ts (5 files)
• And more...

Phase 2: Create Missing Domains

Estimated time: 1 hour

A. Create Auth Domain

packages/domain/auth/
  contract.ts     - User, AuthenticatedUser, UserProfile, AuthTokens
  schema.ts       - All auth request/response schemas
  index.ts

B. Create Salesforce Common Types

packages/domain/common/
  salesforce.ts   - SalesforceAccountRecord, SalesforceOrderRecord, etc.

C. Add Missing Common Types

packages/domain/common/
  types.ts        - Add Address, list types (InvoiceList, etc.)

Phase 3: Remove Duplicate Request Schemas

Estimated time: 30 minutes

• Delete packages/schemas/src/integrations/freebit/requests/**
• Delete packages/schemas/src/integrations/whmcs/order.schema.ts (duplicate)
• Update any remaining imports to new paths

Phase 4: Portal Migration (68 files)

Estimated time: 2 hours

Systematically update all Portal files:

• Components
• Hooks
• Services
• Utilities

Phase 5: Clean Up Legacy

Estimated time: 1 hour

1. Delete packages/domain/src/**
2. Archive/remove packages/contracts
3. Archive/remove packages/schemas
4. Archive/remove packages/integrations-*
5. Update tsconfig.json paths
6. Update eslint.config.mjs rules
7. Update documentation

---

⏱️ Realistic Timeline

Phase	Time	Cumulative
Phase 1: Fix BFF bare imports	45 min	45 min
Phase 2: Create missing domains	1 hour	1h 45min
Phase 3: Remove duplicates	30 min	2h 15min
Phase 4: Portal migration	2 hours	4h 15min
Phase 5: Clean up legacy	1 hour	5h 15min

Total: ~5-6 hours of focused work

---

🚦 Decision Point

Option A: Complete Everything Systematically

Pros: Clean result, no tech debt
Cons: 5-6 hours of work
Recommendation: Do this if we have the time

Option B: Incremental Approach

Phase 1 only: Fix bare imports (45 min) → reduces errors significantly
Phase 2 only: Create missing domains (1 hour) → unlocks remaining types
Then: Decide on Portal migration timing
Recommendation: Pragmatic if time-constrained

Option C: Document and Defer

Document current state accurately
Create tracking issues for each phase
Let team prioritize
Recommendation: If other work is more urgent

---

📋 Next Action

I recommend Option B - Incremental Approach:

1. Now: Fix bare imports in BFF (45 min)
2. Next: Create auth/salesforce domains (1 hour)
3. Then: Verify BFF type-checks cleanly
4. Finally: Plan Portal migration with team

Would you like me to proceed with Phase 1 (fixing bare imports)?

---

📝 Lessons Learned

1. Don't claim completion prematurely - Verify with type-check
2. Create duplicates is wasteful - Should have updated references when creating new schemas
3. Audit first, then migrate - Know the scope before starting
4. One domain at a time - Would have been clearer
5. Type-check often - Catches issues early

This is the honest status. Ready to proceed methodically.