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:

```typescript
// ❌ 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.