Assist_Design/DEAD-CODE-REMOVAL.md

Dead Code Removal - Salesforce Account Service

Summary

Removed unused methods from SalesforceAccountService after auditing actual usage across the codebase. The service was incorrectly documented and contained methods that were never called.

---

❌ Dead Code Removed (Never Called)

1. updateWhAccount()

async updateWhAccount(accountId: string, whAccountValue: string): Promise<void>

• Lines Removed: 26 lines
• Supposed Use: Update WH_Account__c field
• Reality: Never called anywhere in the codebase
• Why It Existed: Probably planned but never implemented in workflows

2. upsert()

async upsert(accountData: AccountData): Promise<UpsertResult>

• Lines Removed: 30 lines
• Supposed Use: Create or update Salesforce accounts
• Reality: Never called (comment in salesforce.service.ts claimed it was used in signup, but that was false)
• Why It Existed: Speculative CRUD operation that was never needed
• Business Context: We don't create/upsert Salesforce accounts - they already exist and we only query them

3. getById()

async getById(accountId: string): Promise<SalesforceAccountRecord | null>

• Lines Removed: 18 lines
• Supposed Use: Get account by ID
• Reality: Never called (wrapped by getAccount() in salesforce.service.ts which was also never called)
• Why It Existed: Generic CRUD operation

4. update()

async update(accountId: string, updates: Partial<SalesforceAccountRecord>): Promise<void>

• Lines Removed: 13 lines
• Supposed Use: Generic update operation
• Reality: Never called
• Why It Existed: Generic CRUD operation

5. validateId() Private Helper

private validateId(id: string): string

• Lines Removed: 7 lines
• Why Removed: Duplicate of salesforceIdSchema.parse() - we already validate IDs using Zod schemas
• Pattern: This was manual validation that we just cleaned up in the validation refactor!

---

✅ Methods Kept (Actually Used)

1. findByCustomerNumber()

Used in:

• signup-workflow.service.ts - Line 424
• whmcs-link-workflow.service.ts - Line 122

Purpose: Find Salesforce account by customer number (SF_Account_No__c field) during signup/linking

2. getAccountDetails()

Used in:

• signup-workflow.service.ts - Line 84

Purpose: Check if WH_Account__c field is populated (indicates already linked to WHMCS)

---

📊 Impact

Code Reduction

File	Before	After	Lines Removed
salesforce-account.service.ts	176 lines	88 lines	88 lines (50%)
salesforce.service.ts	151 lines	134 lines	17 lines
Total			105 lines

Methods Removed

• ❌ 3 unused public methods in SalesforceAccountService
• ❌ 1 unused generic method
• ❌ 1 duplicate validation helper
• ❌ 3 wrapper methods in SalesforceService

Interfaces Removed

• ❌ AccountData interface (only used by dead upsert() method)
• ❌ UpsertResult interface (only used by dead upsert() method)

---

🎯 What Actually Happens with Salesforce Accounts

Reality Check

We don't create or modify Salesforce accounts in the customer portal!

Actual Operations:

1. Query by Customer Number - Find existing SF account
2. Check Account Details - Read WH_Account__c to see if already linked
3. Check Internet Eligibility - Done in internet-catalog.service.ts, queries Internet_Eligibility__c field

What We Don't Do:

• ❌ Create Salesforce accounts (they exist in SF already)
• ❌ Update Salesforce account fields (read-only from portal perspective)
• ❌ Upsert accounts (no create/update operations)
• ❌ Generic CRUD operations on accounts

---

🔍 How Was This Missed?

Documentation Was Wrong

File: salesforce.service.ts (Lines 17-21)

/**
 * Used Methods:
 * - findAccountByCustomerNumber() - auth service (WHMCS linking) ✅ TRUE
 * - upsertAccount() - auth service (signup) ❌ FALSE - never called!
 * - getAccount() - users service (profile enhancement) ❌ FALSE - never called!
 */

Validation Was Added to Dead Code

We just spent effort validating methods that were never called:

• Added salesforceIdSchema validation to updateWhAccount() ❌
• Added requiredStringSchema validation to upsert() ❌
• Added validation to getById() ❌

Lesson: Should audit usage BEFORE adding validation/improvements!

---

✅ Fixed Files

1. apps/bff/src/integrations/salesforce/services/salesforce-account.service.ts

• Removed 3 dead public methods
• Removed 2 unused private helpers
• Removed duplicate validation logic
• Added clear documentation about what's actually used
• 88 lines removed

2. apps/bff/src/integrations/salesforce/salesforce.service.ts

• Removed 3 wrapper methods for dead code
• Updated documentation to reflect reality
• Removed unused type imports (AccountData, UpsertResult, SalesforceAccountRecord)
• 17 lines removed

---

🚀 Benefits

1. Clearer Intent

• Service now only contains what's actually needed
• No confusion about which methods are used
• Documentation matches reality

2. Less Maintenance

• 105 fewer lines to maintain
• No dead validation logic
• Simpler service surface

3. Better Security

• Removed write operations that were never supposed to be used
• Clear read-only access pattern to Salesforce accounts
• Less attack surface

4. Accurate Documentation

• Comments now accurately describe what the service does
• Mentions Internet Eligibility checking happens elsewhere
• No misleading "used in X" comments

---

📝 Notes

Internet Eligibility

The user mentioned checking "dwelling type or Internet Eligibility" - this happens in:

• File: apps/bff/src/modules/catalog/services/internet-catalog.service.ts
• Field: Internet_Eligibility__c
• Purpose: Filter available Internet plans based on user's location/eligibility

WH_Account__c Field

This field links Salesforce accounts to WHMCS:

• Set in WHMCS or Salesforce (not in portal)
• Portal only reads it to check if account is already linked
• Used during signup to prevent duplicate links

---

✨ Conclusion

We had 3 unused methods (60% of the service) with validation logic that was never executed!

The cleanup:

• ✅ Removed 105 lines of dead code
• ✅ Fixed misleading documentation
• ✅ Clarified actual business logic
• ✅ Removed unnecessary write operations
• ✅ Simplified service to read-only operations

The service now accurately reflects what the customer portal actually does with Salesforce accounts: read-only queries.