+ Weekend installation (+¥3,000), express setup, or special configuration
+ charges may be added. We'll contact you before applying any additional
+ fees.
+
+
+
+
+
+ );
+ })()}
+ {/* Support Contact */}
+
+
+
+
Need Help?
+
+ Questions about your order? Contact our support team.
+
)}
diff --git a/apps/portal/src/components/checkout/address-confirmation.tsx b/apps/portal/src/components/checkout/address-confirmation.tsx
index 5f162ea6..6b692198 100644
--- a/apps/portal/src/components/checkout/address-confirmation.tsx
+++ b/apps/portal/src/components/checkout/address-confirmation.tsx
@@ -51,7 +51,7 @@ export function AddressConfirmation({
const fetchBillingInfo = useCallback(async () => {
try {
setLoading(true);
- const data = await authenticatedApi.get("/users/billing");
+ const data = await authenticatedApi.get("/me/billing");
setBillingInfo(data);
// Since address is required at signup, it should always be complete
@@ -208,8 +208,8 @@ export function AddressConfirmation({
Internet Installation Address Verification Required
- Please verify this is the correct address for your internet installation.
- A technician will visit this location for setup.
+ Please verify this is the correct address for your internet installation. A
+ technician will visit this location for setup.
diff --git a/apps/portal/src/components/layout/dashboard-layout.tsx b/apps/portal/src/components/layout/dashboard-layout.tsx
index 59b8058a..33500343 100644
--- a/apps/portal/src/components/layout/dashboard-layout.tsx
+++ b/apps/portal/src/components/layout/dashboard-layout.tsx
@@ -42,7 +42,6 @@ const navigation = [
name: "Billing",
icon: CreditCardIcon,
children: [
- { name: "Address & Info", href: "/account/billing" },
{ name: "Invoices", href: "/billing/invoices" },
{ name: "Payment Methods", href: "/billing/payments" },
],
diff --git a/apps/portal/src/hooks/use-profile-completion.ts b/apps/portal/src/hooks/use-profile-completion.ts
index 2e37d597..d4dba509 100644
--- a/apps/portal/src/hooks/use-profile-completion.ts
+++ b/apps/portal/src/hooks/use-profile-completion.ts
@@ -35,7 +35,7 @@ export function useProfileCompletion(): ProfileCompletionStatus {
useEffect(() => {
const checkProfileCompletion = async () => {
try {
- const billingInfo = await authenticatedApi.get("/users/billing");
+ const billingInfo = await authenticatedApi.get("/me/billing");
setIsComplete(billingInfo.isComplete);
} catch (error) {
console.error("Failed to check profile completion:", error);
diff --git a/apps/portal/src/types/world-countries.d.ts b/apps/portal/src/types/world-countries.d.ts
new file mode 100644
index 00000000..f16d8c7e
--- /dev/null
+++ b/apps/portal/src/types/world-countries.d.ts
@@ -0,0 +1,15 @@
+declare module "world-countries" {
+ interface Country {
+ name: {
+ common: string;
+ official: string;
+ };
+ cca2: string;
+ cca3: string;
+ ccn3: string;
+ cioc: string;
+ }
+
+ const countries: Country[];
+ export default countries;
+}
diff --git a/docs/ADDRESS_SYSTEM.md b/docs/ADDRESS_SYSTEM.md
new file mode 100644
index 00000000..dedd57dd
--- /dev/null
+++ b/docs/ADDRESS_SYSTEM.md
@@ -0,0 +1,351 @@
+# Address System Documentation
+
+## Overview
+
+Our address system follows a **clean, logical flow** where address is **required at signup** and managed throughout the user lifecycle. This eliminates surprises during checkout and ensures data integrity.
+
+## 🎯 Core Logic
+
+```
+Registration → Required Address → WHMCS Storage → Order Snapshots
+```
+
+## Architecture
+
+```mermaid
+graph TD
+ A[User Registration] --> B[Required Address Validation]
+ B --> C[WHMCS Client Creation]
+ C --> D[Complete Profile]
+
+ D --> E[Checkout Flow]
+ E --> F{Order Type?}
+ F -->|Internet| G[Explicit Address Verification]
+ F -->|Other| H[Auto-Confirm Address]
+
+ G --> I[Address Snapshot]
+ H --> I
+ I --> J[Salesforce Order]
+
+ D --> K[Profile Management]
+ K --> L[Address Updates]
+ L --> M[WHMCS Sync]
+```
+
+## Key Components
+
+### Backend
+- `SignupDto` - Address required at registration
+- `UsersService.updateBillingInfo()` - WHMCS sync
+- `OrderBuilder.addAddressSnapshot()` - Salesforce snapshots
+
+### Frontend
+- `AddressConfirmation` - Checkout verification
+- `ProfileCompletionGuard` - Handles incomplete profiles
+- `/account/billing` - Address management
+
+## Order Type Flows
+
+| Order Type | Address Behavior |
+|------------|------------------|
+| **Internet** | ✅ Explicit verification required (technician visit) |
+| **SIM/VPN/Other** | ✅ Auto-confirm (exists from signup) |
+
+## Implementation
+
+### 1. Signup Flow (Required Address)
+
+#### Backend Validation
+```typescript
+// apps/bff/src/auth/dto/signup.dto.ts
+export class AddressDto {
+ @IsNotEmpty() line1: string; // Required
+ @IsOptional() line2?: string; // Optional
+ @IsNotEmpty() city: string; // Required
+ @IsNotEmpty() state: string; // Required
+ @IsNotEmpty() postalCode: string; // Required
+ @IsNotEmpty() country: string; // Required
+}
+
+export class SignupDto {
+ @ValidateNested()
+ @Type(() => AddressDto)
+ address: AddressDto; // ✅ REQUIRED - not optional
+}
+```
+
+#### WHMCS Client Creation
+```typescript
+// apps/bff/src/auth/auth.service.ts
+await this.whmcsService.addClient({
+ address1: address.line1, // Required field
+ address2: address.line2 || "", // Optional field
+ city: address.city, // Required field
+ state: address.state, // Required field
+ postcode: address.postalCode, // Required field
+ country: address.country, // Required field
+});
+```
+
+### 2. Checkout Flow
+
+#### Address Confirmation Logic
+```typescript
+// apps/portal/src/components/checkout/address-confirmation.tsx
+// Since address is required at signup, it should always be complete
+if (requiresAddressVerification) {
+ // Internet orders: require explicit verification
+ setAddressConfirmed(false);
+ onAddressIncomplete(); // Keep disabled until confirmed
+} else {
+ // Other orders: auto-confirm since address exists from signup
+ onAddressConfirmed(data.address);
+ setAddressConfirmed(true);
+}
+```
+
+#### Internet Order Verification
+```typescript
+{isInternetOrder && !addressConfirmed && (
+
+
+ Internet Installation Address Verification Required
+
+
+ Please verify this is the correct address for your internet installation.
+ A technician will visit this location for setup.
+
+
+)}
+```
+
+### 3. Address Updates & WHMCS Sync
+
+```typescript
+// apps/bff/src/users/users.service.ts
+async updateBillingInfo(userId: string, billingData: UpdateBillingDto): Promise {
+ const mapping = await this.mappingsService.findByUserId(userId);
+
+ // Prepare WHMCS update data
+ const whmcsUpdateData = {
+ address1: billingData.street,
+ address2: billingData.streetLine2,
+ city: billingData.city,
+ state: billingData.state,
+ postcode: billingData.postalCode,
+ country: billingData.country,
+ };
+
+ // Update in WHMCS (authoritative source)
+ await this.whmcsService.updateClient(mapping.whmcsClientId, whmcsUpdateData);
+}
+```
+
+### 4. Order Address Snapshots
+
+```typescript
+// apps/bff/src/orders/services/order-builder.service.ts
+private async addAddressSnapshot(orderFields: Record, userId: string, body: CreateOrderBody): Promise {
+ const billingInfo = await this.usersService.getBillingInfo(userId);
+ const orderAddress = (body.configurations as any)?.address;
+ const addressChanged = !!(orderAddress);
+ const addressToUse = orderAddress || billingInfo.address;
+
+ // Combine street lines for Salesforce
+ const fullStreet = [addressToUse?.street, addressToUse?.streetLine2]
+ .filter(Boolean)
+ .join(", ");
+
+ // Always populate billing address fields
+ orderFields["BillToStreet"] = fullStreet || "";
+ orderFields["BillToCity"] = addressToUse?.city || "";
+ orderFields["BillToState"] = addressToUse?.state || "";
+ orderFields["BillToPostalCode"] = addressToUse?.postalCode || "";
+ orderFields["BillToCountry"] = addressToUse?.country || "";
+
+ // Set change flag
+ orderFields["Address_Changed__c"] = addressChanged;
+}
+```
+
+## Field Mapping
+
+### WHMCS ↔ Internal ↔ Salesforce
+```
+WHMCS → Internal → Salesforce Order
+address1 → street → BillToStreet (combined)
+address2 → streetLine2 → BillToStreet (combined)
+city → city → BillToCity
+state → state → BillToState
+postcode → postalCode → BillToPostalCode
+country → country → BillToCountry
+
+// Change detection
+N/A → addressChanged → Address_Changed__c (boolean)
+```
+
+## API Reference
+
+### Address Management
+```typescript
+// Get current address
+GET /api/users/billing
+Response: {
+ address: {
+ street: string | null;
+ streetLine2: string | null;
+ city: string | null;
+ state: string | null;
+ postalCode: string | null;
+ country: string | null;
+ };
+ isComplete: boolean;
+}
+
+// Update address
+PATCH /api/users/billing
+Body: {
+ street?: string;
+ streetLine2?: string;
+ city?: string;
+ state?: string;
+ postalCode?: string;
+ country?: string;
+}
+```
+
+## Quick Patterns
+
+### Protect Route with Profile Completion
+```tsx
+
+
+
+```
+
+### Handle Address in Checkout
+```tsx
+
+```
+
+### Check Profile Completion
+```tsx
+const { isComplete, loading, redirectToCompletion } = useProfileCompletion();
+```
+
+## User Flows
+
+### 1. New User Registration
+1. User fills registration form with **required address**
+2. Backend validates all address fields
+3. WHMCS client created with complete address
+4. User can immediately access all features
+
+### 2. Internet Order Checkout
+1. User selects Internet service
+2. Address confirmation component loads
+3. Shows current address with verification requirement
+4. User must explicitly confirm installation address
+5. Order created with address snapshot
+
+### 3. Other Order Checkout
+1. User selects SIM/VPN/Other service
+2. Address confirmation component loads
+3. Auto-confirms address (exists from signup)
+4. Order created with address snapshot
+
+### 4. Address Updates
+1. User goes to `/account/billing`
+2. Can edit and save address changes
+3. Changes sync to WHMCS immediately
+4. Future orders use updated address
+
+## Testing
+
+### Quick Commands
+```bash
+# Test required address validation
+curl -X POST /api/auth/signup -d '{"address": {...}}'
+
+# Get user address
+curl -X GET /api/users/billing
+
+# Update address
+curl -X PATCH /api/users/billing -d '{"street": "New St"}'
+```
+
+### Test Scenarios
+1. **New User Signup**: Verify address is required and validated
+2. **Internet Order**: Verify explicit address confirmation required
+3. **SIM Order**: Verify address auto-confirmed
+4. **Address Update**: Verify WHMCS sync works
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Address not found during checkout"
+- **Cause**: User somehow has incomplete profile
+- **Solution**: `ProfileCompletionGuard` will redirect to completion
+
+#### "Internet order won't submit"
+- **Cause**: Address not explicitly confirmed
+- **Solution**: User must click "Confirm Installation Address"
+
+#### "Address changes not saving"
+- **Cause**: WHMCS API connection issue
+- **Solution**: Check WHMCS credentials and API access
+
+### Quick Debug
+1. **Address not required?** → Check `SignupDto.address` is not `@IsOptional()`
+2. **Internet order auto-confirms?** → Check `orderType === "Internet"` logic
+3. **Address not in Salesforce?** → Check `addAddressSnapshot()` call
+4. **WHMCS not updating?** → Check API credentials and `updateClient()` method
+
+## Configuration
+
+### Environment Variables
+```bash
+# WHMCS API
+WHMCS_API_URL=https://your-whmcs.com/includes/api.php
+WHMCS_API_IDENTIFIER=your_api_identifier
+WHMCS_API_SECRET=your_api_secret
+
+# Salesforce Field Mapping (optional overrides)
+ORDER_ADDRESS_CHANGED_FIELD=Address_Changed__c
+ORDER_BILL_TO_STREET_FIELD=BillToStreet
+ORDER_BILL_TO_CITY_FIELD=BillToCity
+ORDER_BILL_TO_STATE_FIELD=BillToState
+ORDER_BILL_TO_POSTAL_CODE_FIELD=BillToPostalCode
+ORDER_BILL_TO_COUNTRY_FIELD=BillToCountry
+```
+
+## Benefits
+
+### ✅ **User Experience**
+- No surprise address requirements during checkout
+- Clear completion flows for edge cases
+- Order-type specific verification (Internet vs Others)
+
+### ✅ **Data Integrity**
+- Address required at source (signup)
+- Single source of truth (WHMCS)
+- Point-in-time snapshots (Salesforce orders)
+
+### ✅ **Performance**
+- No unnecessary dashboard banners
+- Simplified checkout validation
+- Efficient profile completion checks
+
+### ✅ **Maintainability**
+- Logical flow from signup to order
+- Reusable profile completion components
+- Clean separation of concerns
+
+---
+
+*This address system provides a clean, logical, and modern approach to address management with required addresses at signup and intelligent order-type specific flows.*
\ No newline at end of file
diff --git a/docs/CHECKOUT-MIGRATION-GUIDE.md b/docs/CHECKOUT-MIGRATION-GUIDE.md
deleted file mode 100644
index 6e387b6f..00000000
--- a/docs/CHECKOUT-MIGRATION-GUIDE.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# Checkout Page Migration Guide
-
-## 🎯 **The Problem: Fragile Name Matching**
-
-### ❌ **Old Approach (Current checkout.tsx)**
-```typescript
-// BAD: Frontend guessing based on names and SKUs
-const hikariService = addons.find(addon =>
- addon.sku.includes('HOME-PHONE') || addon.sku.includes('HIKARI-DENWA')
-);
-
-const installation = installations.find(inst =>
- inst.name.toLowerCase().includes(selections.install.toLowerCase())
-);
-
-// BAD: Hardcoded business logic in frontend
-if (billingCycle === "Monthly") {
- monthlyTotal += price;
-} else {
- oneTimeTotal += price;
-}
-```
-
-**Problems:**
-- ❌ SKU/name parsing is fragile
-- ❌ Business logic mixed in frontend
-- ❌ Breaks when products are renamed
-- ❌ No type safety
-- ❌ Hard to maintain and extend
-
-## ✅ **New Approach: Structured Data**
-
-### **1. Backend Organizes Everything**
-```typescript
-// GOOD: Backend provides structured, typed data
-const catalog = await api.get("/catalog/structured");
-
-// No guessing needed - everything is properly categorized:
-const hikariService = catalog.internet.addons.find(addon =>
- addon.type === 'hikari-denwa-service' // Type-safe enum!
-);
-
-const installation = catalog.internet.installations.find(inst =>
- inst.type === selections.install // Direct match with enum!
-);
-```
-
-### **2. Pricing from Salesforce Fields**
-```typescript
-// GOOD: Uses actual Salesforce fields
-return {
- monthlyPrice: addon.monthlyPrice, // From PricebookEntry + Billing_Cycle__c
- activationPrice: addon.activationPrice, // From PricebookEntry + Billing_Cycle__c
- autoAdd: addon.autoAdd, // From Auto_Add__c field
- requiredWith: addon.requiredWith // From Required_Products__c field
-};
-```
-
-### **3. Type-Safe Order Building**
-```typescript
-// GOOD: Strongly typed, no string matching
-interface OrderItem {
- name: string;
- sku: string;
- monthlyPrice?: number;
- oneTimePrice?: number;
- type: 'service' | 'installation' | 'addon';
- autoAdded?: boolean;
-}
-
-const buildOrderItems = (): OrderItem[] => {
- const items: OrderItem[] = [];
-
- // Direct SKU lookup - no name matching!
- const mainService = catalog.internet.plans.find(p => p.sku === selections.planSku);
-
- // Type-based lookup - no string parsing!
- const hikariService = catalog.internet.addons.find(a => a.type === 'hikari-denwa-service');
-
- return items;
-};
-```
-
-## 🔄 **Migration Steps**
-
-### **Step 1: Add Structured Endpoint**
-```typescript
-// In catalog.controller.ts
-@Get('structured')
-async getStructuredCatalog() {
- return this.structuredCatalogService.getStructuredCatalog();
-}
-```
-
-### **Step 2: Update Frontend API Calls**
-```typescript
-// OLD: Fragile flat structure
-const catalog = await api.get("/catalog");
-const addons = await api.get("/catalog/internet/addons");
-
-// NEW: Structured data
-const catalog = await api.get("/catalog/structured");
-// All data is properly organized within the response!
-```
-
-### **Step 3: Replace Name Matching Logic**
-```typescript
-// OLD: String matching
-const isGold = plan.name?.toLowerCase().includes('gold');
-const hikariAddon = addons.find(a => a.sku.includes('HIKARI'));
-
-// NEW: Structured properties
-const isGold = plan.tier === 'Gold';
-const hikariAddon = addons.find(a => a.type === 'hikari-denwa-service');
-```
-
-### **Step 4: Use Type-Safe Calculations**
-```typescript
-// OLD: Manual calculation with guesswork
-let monthlyTotal = 0;
-if (hikariDenwa !== "None") {
- const addon = addons.find(a => a.sku.includes('PHONE'));
- if (addon?.monthlyPrice) monthlyTotal += addon.monthlyPrice;
-}
-
-// NEW: Structured calculation
-const orderItems = buildOrderItems();
-const monthlyTotal = orderItems.reduce((sum, item) => sum + (item.monthlyPrice || 0), 0);
-```
-
-## 📊 **Benefits Comparison**
-
-| Aspect | Old Approach | New Structured Approach |
-|--------|-------------|------------------------|
-| **Product Identification** | String matching | Type-safe enums |
-| **Pricing Source** | URL params/hardcoded | Live Salesforce PricebookEntry |
-| **Business Logic** | Frontend guesswork | Backend organization |
-| **Extensibility** | Break on new products | Auto-includes new products |
-| **Maintainability** | Fragile string matching | Robust field-based logic |
-| **Type Safety** | Weak typing | Strong TypeScript types |
-| **Error Prone** | High (string matching) | Low (structured data) |
-
-## 🎯 **Example: Adding New Product Type**
-
-### **Old Way (Breaks)**
-```typescript
-// ❌ NEW PRODUCT: "Premium Support" would break existing code
-const premiumSupport = addons.find(addon =>
- addon.sku.includes('PREMIUM-SUPPORT') // This wouldn't match anything!
-);
-```
-
-### **New Way (Works Automatically)**
-```typescript
-// ✅ NEW PRODUCT: Just add to Salesforce with proper fields
-// Addon_Type__c = "Premium Support"
-// Backend automatically categorizes it:
-
-const premiumSupport = catalog.internet.addons.find(addon =>
- addon.type === 'premium-support' // Type mapping handled by backend
-);
-```
-
-## 🚀 **Implementation Files**
-
-### **Backend Files Created/Updated:**
-- `apps/bff/src/catalog/structured-catalog.service.ts` - Main structured service
-- `apps/bff/src/catalog/catalog.controller.ts` - Added `/catalog/structured` endpoint
-- `apps/bff/src/catalog/catalog.module.ts` - Service registration
-
-### **Frontend Implementation:**
-- `apps/portal/src/app/checkout/page.tsx` - Clean implementation using shared types
-
-### **Documentation:**
-- `docs/STRUCTURED-CATALOG-EXAMPLE.md` - Detailed comparison
-- `docs/CHECKOUT-MIGRATION-GUIDE.md` - This migration guide
-
-## 🎉 **Migration Result**
-
-### **Before:**
-- ❌ 31+ instances of fragile `.includes()` matching
-- ❌ Hardcoded pricing fallbacks
-- ❌ Business logic scattered in frontend
-- ❌ Breaks when products are renamed
-
-### **After:**
-- ✅ Zero string matching - everything type-safe
-- ✅ Live Salesforce pricing throughout
-- ✅ Business logic centralized in backend
-- ✅ Extensible - new products work automatically
-- ✅ Maintainable and robust architecture
-
-## 🔧 **Next Steps**
-
-1. **Test the structured endpoint**: `GET /api/catalog/structured`
-2. **Update frontend pages** to use structured data
-3. **Remove name matching logic** from existing components
-4. **Add Salesforce fields** if any are missing:
- ```sql
- Internet_Plan_Tier__c (Picklist): Silver | Gold | Platinum
- Addon_Type__c (Text): Hikari Denwa Service | Premium Support
- Installation_Type__c (Picklist): One-time | 12-Month | 24-Month
- ```
-
-The structured approach eliminates all the fragile name matching and makes the system much more robust and maintainable! 🎯
diff --git a/docs/CLEAN-ARCHITECTURE-SUMMARY.md b/docs/CLEAN-ARCHITECTURE-SUMMARY.md
deleted file mode 100644
index 02bb2064..00000000
--- a/docs/CLEAN-ARCHITECTURE-SUMMARY.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Clean Architecture Implementation Summary
-
-## 🎯 **Problem Solved**
-
-### ❌ **Before: Suboptimal Structure**
-```
-- Large monolithic services (700+ lines each)
-- Duplicate logic across services
-- Multiple services with overlapping responsibilities
-- Type duplication between backend and frontend
-- No single source of truth for types
-- Fragile name matching in frontend
-```
-
-### ✅ **After: Clean, Maintainable Architecture**
-
-## 🏗️ **Final Architecture**
-
-### **Backend Structure**
-```
-📁 shared/types/
-└── catalog.types.ts # 🔥 SINGLE SOURCE OF TRUTH
-
-📁 catalog/
-├── 📁 services/
-│ ├── base-catalog.service.ts # Common Salesforce operations (~120 lines)
-│ ├── internet-catalog.service.ts # Internet-specific logic (~180 lines)
-│ ├── sim-catalog.service.ts # SIM-specific logic (~140 lines)
-│ ├── vpn-catalog.service.ts # VPN-specific logic (~100 lines)
-│ └── catalog-orchestrator.service.ts # Coordinates everything (~150 lines)
-├── catalog.controller.ts # Routes to orchestrator only
-└── catalog.module.ts # Clean service registration
-
-📁 orders/
-├── 📁 services/
-│ ├── order-validator.service.ts # Validation only (~180 lines)
-│ ├── order-builder.service.ts # Order header building (~90 lines)
-│ ├── order-item-builder.service.ts # OrderItem creation (~160 lines)
-│ └── order-orchestrator.service.ts # Coordinates flow (~120 lines)
-├── orders.controller.ts # Routes to orchestrator only
-└── orders.module.ts # Clean service registration
-```
-
-### **Frontend Structure**
-```
-📁 portal/src/shared/types/
-└── catalog.types.ts # Re-exports backend types + utilities
-
-📁 portal/src/app/checkout/
-└── page.tsx # Uses shared types, zero duplication
-```
-
-## 🎯 **Key Principles Applied**
-
-### **1. Single Responsibility Principle**
-- Each service has ONE clear purpose
-- Easy to test, maintain, and extend
-- No mixed concerns
-
-### **2. Single Source of Truth**
-```typescript
-// ✅ Types defined once in backend
-export interface InternetPlan {
- id: string;
- name: string;
- sku: string;
- tier: 'Silver' | 'Gold' | 'Platinum';
- // ...
-}
-
-// ✅ Frontend imports same types
-import { InternetPlan, StructuredCatalog } from '@/shared/types/catalog.types';
-```
-
-### **3. Reusable Utilities**
-```typescript
-// ✅ Business logic centralized in shared utilities
-export function buildOrderItems(
- catalog: StructuredCatalog,
- orderType: ProductType,
- selections: Record
-): OrderItem[] {
- // Single implementation, used everywhere
-}
-
-export function calculateTotals(items: OrderItem[]): OrderTotals {
- // Reusable across all components
-}
-```
-
-### **4. Clean Abstractions**
-```typescript
-// ✅ Controller uses only orchestrator
-@Controller('catalog')
-export class CatalogController {
- constructor(private catalogOrchestrator: CatalogOrchestrator) {}
-
- @Get('structured')
- async getStructuredCatalog(): Promise {
- return this.catalogOrchestrator.getStructuredCatalog();
- }
-}
-```
-
-## 🚀 **Benefits Achieved**
-
-| Aspect | Before | After |
-|--------|--------|--------|
-| **Services** | 2 large (700+ lines each) | 9 focused (~120 lines each) |
-| **Type Duplication** | Multiple definitions | Single source of truth |
-| **Business Logic** | Scattered across frontend | Centralized utilities |
-| **Maintainability** | Difficult | Simple |
-| **Testability** | Hard to isolate | Easy focused testing |
-| **Code Reuse** | Copy-paste | Shared utilities |
-| **Architecture** | Monolithic | Modular |
-
-## 📊 **Line Count Reduction**
-
-### **Before (Monolithic)**
-```
-Large monolithic services: 1500+ lines
-Duplicate types and logic
-Mixed concerns and responsibilities
-TOTAL: 1500+ lines (hard to maintain)
-```
-
-### **After (Modular)**
-```
-catalog.types.ts: 130 lines (shared)
-base-catalog.service.ts: 120 lines
-internet-catalog.service.ts: 180 lines
-sim-catalog.service.ts: 140 lines
-vpn-catalog.service.ts: 100 lines
-catalog-orchestrator.service.ts: 150 lines
-order-validator.service.ts: 180 lines
-order-builder.service.ts: 90 lines
-order-item-builder.service.ts: 160 lines
-order-orchestrator.service.ts: 120 lines
-TOTAL: 1370 lines (9% reduction + much cleaner)
-```
-
-## 🎯 **Usage Examples**
-
-### **Backend Service Usage**
-```typescript
-// Get complete catalog (cached)
-const catalog = await this.catalogOrchestrator.getStructuredCatalog();
-
-// Get specific category data (cached)
-const internetData = await this.catalogOrchestrator.getInternetCatalog();
-
-// Direct service access if needed
-const plans = await this.internetCatalog.getPlans();
-```
-
-### **Frontend Usage**
-```typescript
-// Import shared types and utilities
-import {
- StructuredCatalog,
- buildOrderItems,
- calculateTotals,
- buildOrderSKUs
-} from '@/shared/types/catalog.types';
-
-// Use shared business logic
-const orderItems = buildOrderItems(catalog, orderType, selections);
-const totals = calculateTotals(orderItems);
-const skus = buildOrderSKUs(orderItems);
-```
-
-### **Testing**
-```typescript
-// Test individual focused services
-describe('InternetCatalogService', () => {
- // Test only Internet-specific logic (~50 test lines vs 200+ before)
-});
-
-describe('buildOrderItems', () => {
- // Test shared utility function directly
-});
-```
-
-## 🔄 **API Endpoints**
-
-### **Simplified Controller**
-```typescript
-GET /api/catalog → orchestrator.getLegacyCatalog()
-GET /api/catalog/structured → orchestrator.getStructuredCatalog() ⭐ RECOMMENDED
-GET /api/catalog/internet/addons → orchestrator.getInternetCatalog().addons
-POST /api/orders → orderOrchestrator.createOrder()
-```
-
-## 🎉 **Clean Architecture Achieved**
-
-### **✅ Single Source of Truth**
-- Types defined once in backend
-- Frontend imports same types
-- Zero duplication
-
-### **✅ Focused Services**
-- Each service has one clear responsibility
-- Easy to test and maintain
-- No mixed concerns
-
-### **✅ Reusable Utilities**
-- Business logic centralized
-- Shared across components
-- No copy-paste code
-
-### **✅ Clean Abstractions**
-- Controllers use orchestrators only
-- Clear service boundaries
-- Easy to extend
-
-### **✅ Maintainable Structure**
-- Easy to find code
-- Simple to make changes
-- Clear ownership
-
-## 🚀 **Extension Process**
-
-### **Adding New Product Type**
-```typescript
-// 1. Add types to shared/types/catalog.types.ts
-export interface IotDevice extends BaseProduct {
- deviceType: string;
- connectivity: string;
-}
-
-// 2. Create focused service
-@Injectable()
-export class IotCatalogService extends BaseCatalogService {
- async getDevices(): Promise {
- // ~100 lines of IoT-specific logic
- }
-}
-
-// 3. Update orchestrator
-const [internet, sim, vpn, iot] = await Promise.all([
- this.internetCatalog.getCatalogData(),
- this.simCatalog.getCatalogData(),
- this.vpnCatalog.getCatalogData(),
- this.iotCatalog.getCatalogData() // Add new service
-]);
-
-// 4. Frontend automatically gets new types and utilities!
-```
-
-## 🏆 **Result: Perfect Architecture**
-
-✅ **Single Source of Truth**: All types defined once
-✅ **Focused Services**: Each service has clear responsibility
-✅ **Reusable Utilities**: Business logic shared across components
-✅ **Clean Dependencies**: Controllers use orchestrators only
-✅ **Easy Testing**: Focused, isolated test suites
-✅ **Simple Extension**: Add new features without touching existing code
-✅ **Zero Duplication**: No repeated types or logic anywhere
-
-The architecture is now **clean, maintainable, and extensible**! 🎯
diff --git a/docs/FIELD-MAPPING-MIGRATION-GUIDE.md b/docs/FIELD-MAPPING-MIGRATION-GUIDE.md
deleted file mode 100644
index 2265f503..00000000
--- a/docs/FIELD-MAPPING-MIGRATION-GUIDE.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# Field Mapping Migration Guide
-
-This guide provides step-by-step instructions for migrating services to use the simplified centralized field mapping system.
-
-## Overview
-
-The simplified field mapping system in `apps/bff/src/common/config/field-map.ts` provides essential field coverage for Internet, SIM, and VPN products with a clean, maintainable structure. Complex configuration logic is handled by Salesforce flows rather than product fields.
-
-## What's New
-
-### Simplified Structure
-- **Core Product fields**: Essential catalog fields only (StockKeepingUnit, category, visibility, pricing)
-- **Service-specific fields**: Minimal fields per product type (Internet tier, SIM data size, etc.)
-- **Configuration logic**: Moved to Salesforce flows for Gold/Platinum Internet plans
-- **Family discount logic**: Handled in personalized catalog service
-
-### Key Simplifications
-- **Removed complex configuration fields**: Access mode, service speed, etc. determined by Salesforce
-- **Streamlined VPN products**: Region selection at order time, not product level
-- **Clean Internet structure**: Silver (customer configures) vs Gold/Platinum (Salesforce configures)
-
-## Migration Steps
-
-### 1. Update Catalog Service
-
-**Current hardcoded usage:**
-```typescript
-// In catalog.service.ts
-const soql = `SELECT Id, Name, ${skuField}, Product2Categories1__c, Portal_Catalog__c FROM Product2...`
-```
-
-**Migrate to:**
-```typescript
-import { getSalesforceFieldMap, getProductQueryFields } from "../common/config/field-map";
-
-// Option 1: Use helper function (recommended)
-const soql = `SELECT ${getProductQueryFields()} FROM Product2 WHERE ${fields.product.portalCatalog} = true`;
-
-// Option 2: Use individual fields
-const fields = getSalesforceFieldMap();
-const soql = `SELECT Id, Name, ${fields.product.sku}, ${fields.product.portalCategory}, ${fields.product.portalCatalog} FROM Product2...`;
-```
-
-### 2. Update Orders Service
-
-**Current mixed usage:**
-```typescript
-// Some fields use mapping, others are hardcoded
-orderFields.Order_Type__c = normalizedType;
-orderFields.Activation_Type__c = body.selections.activationType;
-orderFields.Internet_Plan_Tier__c = body.selections.tier;
-```
-
-**Migrate to:**
-```typescript
-const fields = getSalesforceFieldMap();
-
-orderFields[fields.order.orderType] = normalizedType;
-orderFields[fields.order.activationType] = body.selections.activationType;
-orderFields[fields.order.internetPlanTier] = body.selections.tier;
-orderFields[fields.order.accessMode] = body.selections.mode;
-orderFields[fields.order.serviceSpeed] = body.selections.speed;
-orderFields[fields.order.installmentPlan] = body.selections.install;
-orderFields[fields.order.weekendInstall] = body.selections.weekend;
-```
-
-### 3. Update Account Service
-
-**Current hardcoded usage:**
-```typescript
-// In salesforce-account.service.ts
-WHERE SF_Account_No__c = '${this.safeSoql(customerNumber.trim())}'
-```
-
-**Migrate to:**
-```typescript
-import { getSalesforceFieldMap } from "../../../common/config/field-map";
-
-const fields = getSalesforceFieldMap();
-WHERE ${fields.account.customerNumber} = '${this.safeSoql(customerNumber.trim())}'
-```
-
-### 4. Add Personalized Catalog Support
-
-**New functionality for Account eligibility:**
-```typescript
-const fields = getSalesforceFieldMap();
-
-// Query account eligibility
-const accountSoql = `SELECT ${fields.account.internetEligibility} FROM Account WHERE Id = '${accountId}'`;
-
-// Filter products by eligibility
-const productSoql = `SELECT ${getProductQueryFields()}
- FROM Product2
- WHERE ${fields.product.portalVisible} = true
- AND ${fields.product.portalInternetOffering} = '${eligibility}'`;
-```
-
-## Service-by-Service Migration Checklist
-
-### ✅ Catalog Service
-- [ ] Replace hardcoded `Product2Categories1__c` with `fields.product.portalCategory`
-- [ ] Replace hardcoded `Portal_Catalog__c` with `fields.product.portalCatalog`
-- [ ] Replace hardcoded `Portal_Accessible__c` with `fields.product.portalAccessible`
-- [ ] Use `getProductQueryFields()` for standard queries
-- [ ] Add personalized catalog support using `fields.account.internetEligibility`
-
-### ✅ Orders Service
-- [ ] Replace all hardcoded Order fields with field mapping
-- [ ] Update Order query to use `getOrderQueryFields()`
-- [ ] Replace hardcoded `Activation_Status__c`, `Activation_Type__c`, etc.
-- [ ] Update MNP field usage to use `fields.order.mnp.*`
-- [ ] Replace `WHMCS_Order_ID__c` with `fields.order.whmcsOrderId`
-
-### ✅ Account Service
-- [ ] Replace `SF_Account_No__c` with `fields.account.customerNumber`
-- [ ] Add eligibility field queries using `fields.account.internetEligibility`
-
-### ✅ User Service
-- [ ] Update buildSalesforceUpdate to use field mapping for custom fields
-- [ ] Ensure consistency with Account service field usage
-
-## Environment Variable Support
-
-All field mappings support environment variable overrides:
-
-```bash
-# Account fields
-ACCOUNT_INTERNET_ELIGIBILITY_FIELD=Custom_Internet_Eligibility__c
-ACCOUNT_CUSTOMER_NUMBER_FIELD=Custom_Account_Number__c
-
-# Product fields
-PRODUCT_PORTAL_CATALOG_FIELD=Custom_Portal_Catalog__c
-PRODUCT_PORTAL_ACCESSIBLE_FIELD=Custom_Portal_Accessible__c
-PRODUCT_PORTAL_CATEGORY_FIELD=Custom_Product2Categories1__c
-
-# Order fields
-ORDER_ACTIVATION_TYPE_FIELD=Custom_Activation_Type__c
-ORDER_INTERNET_PLAN_TIER_FIELD=Custom_Plan_Tier__c
-
-# And many more...
-```
-
-## Testing Strategy
-
-1. **Unit Tests**: Update tests to use field mapping instead of hardcoded values
-2. **Integration Tests**: Verify SOQL queries work with mapped fields
-3. **Environment Tests**: Test with different field mappings via env vars
-
-## Rollback Plan
-
-If issues arise, you can quickly rollback by:
-1. Setting environment variables to original field names
-2. The field mapping defaults ensure backward compatibility
-3. No database or Salesforce schema changes required
-
-## Benefits After Migration
-
-1. **Single Source of Truth**: All field references in one place
-2. **Environment Flexibility**: Easy customization per environment
-3. **Documentation Alignment**: Perfect match with portal documentation
-4. **Type Safety**: Strong TypeScript typing for all field references
-5. **Maintainability**: Changes only needed in field mapping file
-
-## Next Steps
-
-1. Migrate services one by one following this guide
-2. Update unit tests to use field mapping
-3. Test in development environment
-4. Update documentation with new patterns
-5. Consider adding field validation at startup
diff --git a/docs/FINAL-CLEAN-ARCHITECTURE.md b/docs/FINAL-CLEAN-ARCHITECTURE.md
deleted file mode 100644
index a9b7b18f..00000000
--- a/docs/FINAL-CLEAN-ARCHITECTURE.md
+++ /dev/null
@@ -1,185 +0,0 @@
-# Final Clean Architecture - No Legacy Code
-
-## ✅ **What Was Cleaned Up**
-
-### **Deleted Legacy Files**
-- ❌ `apps/bff/src/catalog/catalog.service.ts` (700+ lines, monolithic)
-- ❌ `apps/bff/src/catalog/structured-catalog.service.ts` (redundant)
-- ❌ `apps/bff/src/orders/orders.service.ts` (400+ lines, monolithic)
-- ❌ `apps/portal/src/app/checkout/improved-checkout.tsx` (example file)
-
-### **Replaced With Clean Implementation**
-- ✅ `apps/portal/src/app/checkout/page.tsx` - Clean checkout using shared types
-- ✅ `apps/bff/src/catalog/catalog.controller.ts` - Uses only CatalogOrchestrator
-- ✅ `apps/bff/src/orders/orders.controller.ts` - Uses only OrderOrchestrator
-
-## 🏗️ **Final Architecture**
-
-### **Backend Structure**
-```
-📁 shared/types/catalog.types.ts # Single source of truth for types
-
-📁 catalog/
-├── 📁 services/
-│ ├── base-catalog.service.ts # Common Salesforce operations
-│ ├── internet-catalog.service.ts # Internet-specific logic
-│ ├── sim-catalog.service.ts # SIM-specific logic
-│ ├── vpn-catalog.service.ts # VPN-specific logic
-│ └── catalog-orchestrator.service.ts # Coordinates everything
-├── catalog.controller.ts # Routes to orchestrator only
-└── catalog.module.ts # Clean service registration
-
-📁 orders/
-├── 📁 services/
-│ ├── order-validator.service.ts # Validation logic only
-│ ├── order-builder.service.ts # Order header building
-│ ├── order-item-builder.service.ts # OrderItem creation
-│ └── order-orchestrator.service.ts # Coordinates order flow
-├── orders.controller.ts # Routes to orchestrator only
-└── orders.module.ts # Clean service registration
-```
-
-### **Frontend Structure**
-```
-📁 portal/src/shared/types/catalog.types.ts # Re-exports backend types + utilities
-📁 portal/src/app/checkout/page.tsx # Uses shared types, zero duplication
-```
-
-## 🎯 **Clean API Endpoints**
-
-```typescript
-// ✅ Catalog endpoints (all use CatalogOrchestrator)
-GET /api/catalog // Legacy format for backward compatibility
-GET /api/catalog/structured // Recommended structured format
-GET /api/catalog/internet/addons // Internet add-ons
-GET /api/catalog/internet/installations // Internet installations
-GET /api/catalog/sim/activation-fees // SIM activation fees
-GET /api/catalog/vpn/activation-fees // VPN activation fees
-GET /api/catalog/sim/addons // SIM add-ons
-
-// ✅ Order endpoints (all use OrderOrchestrator)
-POST /api/orders // Create order
-GET /api/orders/user // Get user's orders
-GET /api/orders/:id // Get specific order
-POST /api/orders/:id/provision // Trigger provisioning
-```
-
-## 🔧 **Service Responsibilities**
-
-### **Catalog Services**
-| Service | Lines | Responsibility |
-|---------|-------|----------------|
-| `BaseCatalogService` | ~120 | Common Salesforce queries, field mapping |
-| `InternetCatalogService` | ~180 | Internet plans, installations, add-ons |
-| `SimCatalogService` | ~140 | SIM plans, activation fees, add-ons |
-| `VpnCatalogService` | ~100 | VPN plans, activation fees |
-| `CatalogOrchestrator` | ~150 | Coordination, caching, type conversion |
-
-### **Order Services**
-| Service | Lines | Responsibility |
-|---------|-------|----------------|
-| `OrderValidator` | ~180 | Business rule validation, user mapping |
-| `OrderBuilder` | ~90 | Order header field building |
-| `OrderItemBuilder` | ~160 | SKU parsing, OrderItem creation |
-| `OrderOrchestrator` | ~120 | Order creation flow coordination |
-
-## 💡 **Key Features**
-
-### **✅ Single Source of Truth**
-```typescript
-// Types defined once in backend
-export interface StructuredCatalog { ... }
-export interface OrderItem { ... }
-
-// Frontend imports same types
-import { StructuredCatalog, OrderItem } from '@/shared/types/catalog.types';
-```
-
-### **✅ Reusable Utilities**
-```typescript
-// Shared business logic functions
-export function buildOrderItems(catalog, orderType, selections): OrderItem[]
-export function calculateTotals(items: OrderItem[]): OrderTotals
-export function buildOrderSKUs(items: OrderItem[]): string[]
-```
-
-### **✅ Clean Controllers**
-```typescript
-// Controllers use only orchestrators - no direct service dependencies
-@Controller('catalog')
-export class CatalogController {
- constructor(private catalogOrchestrator: CatalogOrchestrator) {}
-}
-
-@Controller('orders')
-export class OrdersController {
- constructor(private orderOrchestrator: OrderOrchestrator) {}
-}
-```
-
-## 📊 **Results**
-
-### **Before vs After**
-| Aspect | Before | After |
-|--------|---------|--------|
-| **Total Services** | 3 monolithic (1500+ lines) | 9 focused (~120 lines each) |
-| **Type Duplication** | Multiple definitions | Single source |
-| **Business Logic** | Copy-paste | Shared utilities |
-| **Controller Dependencies** | Direct service injection | Orchestrator pattern |
-| **Maintainability** | Difficult | Easy |
-| **Testing** | Hard to isolate | Simple focused tests |
-| **Extension** | Breaks existing code | Add new services cleanly |
-
-### **✅ Compilation Status**
-```bash
-> nest build
-# ✅ Build successful - no errors!
-```
-
-## 🚀 **Usage Examples**
-
-### **Frontend Checkout**
-```typescript
-// Clean implementation using shared types and utilities
-import {
- StructuredCatalog,
- buildOrderItems,
- calculateTotals,
- buildOrderSKUs
-} from "@/shared/types/catalog.types";
-
-// Load structured data - no name matching needed!
-const catalog = await api.get("/catalog/structured");
-
-// Use shared utilities - no duplicate logic!
-const orderItems = buildOrderItems(catalog, orderType, selections);
-const totals = calculateTotals(orderItems);
-const skus = buildOrderSKUs(orderItems);
-```
-
-### **Backend Service**
-```typescript
-// Clean orchestrator usage
-const catalog = await this.catalogOrchestrator.getStructuredCatalog();
-const order = await this.orderOrchestrator.createOrder(userId, orderData);
-```
-
-## 🎯 **Architecture Principles Applied**
-
-1. **Single Responsibility** - Each service has one clear purpose
-2. **Single Source of Truth** - Types defined once, used everywhere
-3. **Reusability** - Business logic in shared utilities
-4. **Clean Abstractions** - Controllers use orchestrators only
-5. **Focused Testing** - Easy to test individual components
-6. **Easy Extension** - Add new product types without touching existing code
-
-## 🎉 **Perfect Clean Architecture Achieved!**
-
-✅ **Zero legacy code** - All old services removed
-✅ **Zero duplication** - Types and logic shared across frontend/backend
-✅ **Zero name matching** - Structured data with type-safe operations
-✅ **Zero mixed concerns** - Each service has single responsibility
-✅ **Builds successfully** - All TypeScript errors resolved
-✅ **Fully documented** - Complete implementation guides available
-
-The codebase is now **clean, maintainable, and production-ready**! 🚀
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
index f56df5f3..b167cd6a 100644
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -1,4 +1,4 @@
-# 🚀 Getting Started with Customer Portal
+# 🚀 Getting Started
## ✅ **Environment File Options**
diff --git a/docs/LOGGING-MIGRATION-SUMMARY.md b/docs/LOGGING-MIGRATION-SUMMARY.md
deleted file mode 100644
index 16db5d19..00000000
--- a/docs/LOGGING-MIGRATION-SUMMARY.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# 🔄 Logging Migration Summary
-
-*For complete logging implementation guide, see `LOGGING.md`*
-
-## 🎯 **Migration Status: COMPLETED ✅**
-
-### **✅ What Was Accomplished**
-
-- **Eliminated mixed logging systems** - Single `nestjs-pino` system throughout backend
-- **48 BFF services migrated** - Zero `@nestjs/common` Logger imports remaining
-- **Performance improvements** - 5x faster logging with Pino
-- **Security enhancements** - Automatic sensitive data sanitization
-- **Shared interfaces** - Common logging contracts between frontend and backend
-
-## 🚨 **Key Problems Fixed**
-
-1. **Multiple Logging Systems** → Single `nestjs-pino` system
-2. **Inconsistent Patterns** → Standardized logging across all services
-3. **Security Concerns** → Automatic sanitization of sensitive data
-4. **Performance Issues** → 5x faster logging with Pino
-
-## 🔧 **Migration Tools**
-
-```bash
-# Automated migration script (if needed)
-pnpm dev:migrate-logging
-
-# Manual migration pattern
-# OLD: import { Logger } from "@nestjs/common";
-# NEW: import { Logger } from "nestjs-pino";
-```
-
-## 📊 **Final Status**
-
-### **✅ Completed**
-- [x] All 48 BFF services migrated to `nestjs-pino`
-- [x] Zero `@nestjs/common` Logger imports remaining
-- [x] Security features (sanitization) implemented
-- [x] Performance optimizations applied
-- [x] Comprehensive documentation updated
-
-## 🔍 **Verification Commands**
-
-```bash
-# Verify migration success
-grep -r "import.*Logger.*@nestjs/common" apps/ packages/ # Should return nothing
-grep -r "import.*Logger.*nestjs-pino" apps/ packages/ # Should show migrated imports
-
-# Test logging functionality
-pnpm dev:start && pnpm dev # Check structured log output
-```
-
-## 📚 **Resources**
-
-- **Complete Guide**: `docs/LOGGING.md` - Implementation patterns and best practices
-- **Migration Script**: `pnpm dev:migrate-logging` - Automated migration tool
-- **Shared Interfaces**: `packages/shared/src/logging/` - Common contracts
-
----
-
-**✅ Migration completed successfully!** Your logging system is now centralized, secure, and high-performance.
diff --git a/docs/README.md b/docs/README.md
index ce2b7f2b..24c1914c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,136 +2,65 @@
## 🚀 Quick Start
-### Development Setup
+- **[Getting Started](GETTING_STARTED.md)** - Environment setup and initial configuration
+- **[Development Commands](RUN.md)** - Daily development workflow
+- **[Production Deployment](DEPLOY.md)** - Docker deployment guide
-```bash
-# Copy development environment template
-cp .env.dev.example .env
-# Edit .env with your development values
+## 🏗️ Architecture & Systems
-# Start development
-pnpm dev:start # Start services (PostgreSQL + Redis)
-pnpm dev # Start apps with hot reload
-```
+- **[Address System](ADDRESS_SYSTEM.md)** - Complete address management documentation
+- **[Product Catalog Architecture](PRODUCT-CATALOG-ARCHITECTURE.md)** - SKU-based catalog system
+- **[Portal Data Model](PORTAL-DATA-MODEL.md)** - Database schema and relationships
+- **[Ordering & Provisioning](PORTAL-ORDERING-PROVISIONING.md)** - Order processing flow
+- **[System Structure](STRUCTURE.md)** - Overall system architecture
-### Production Deployment
+## 🔧 Technical References
-```bash
-# Configure for production
-cp .env.production.example .env
-# Edit .env with production values
+- **[Logging](LOGGING.md)** - Logging standards and practices
+- **[Salesforce Products](SALESFORCE-PRODUCTS.md)** - Product configuration in Salesforce
+- **[Portal Roadmap](PORTAL-ROADMAP.md)** - Future development plans
-# Deploy to production
-pnpm prod:deploy
-```
+## 📋 Documentation Standards
-## 📁 Project Structure
+### When to Update Documentation
+
+- **New Features**: Update relevant architecture docs
+- **API Changes**: Update technical references
+- **Configuration Changes**: Update getting started guide
+- **Deployment Changes**: Update deployment guide
+
+### Documentation Structure
```
-📦 Customer Portal
-├── 🚀 apps/ # Applications
-│ ├── portal/ # Next.js frontend
-│ └── bff/ # NestJS backend
-├── 🐳 docker/ # Docker configurations
-│ ├── dev/ # Development (services only)
-│ └── prod/ # Production (complete stack)
-├── 🛠️ scripts/ # Management scripts
-│ ├── dev/manage.sh # Development manager
-│ ├── prod/manage.sh # Production manager
-│ └── plesk-deploy.sh # Plesk deployment
-├── 📚 docs/ # Documentation
-├── 📦 packages/shared/ # Shared utilities
-└── 🔧 Configuration files
+docs/
+├── README.md # This index
+├── GETTING_STARTED.md # Setup & configuration
+├── RUN.md # Development commands
+├── DEPLOY.md # Production deployment
+├── ADDRESS_SYSTEM.md # Address management
+├── PRODUCT-CATALOG-ARCHITECTURE.md # Catalog system
+├── PORTAL-DATA-MODEL.md # Database schema
+├── PORTAL-ORDERING-PROVISIONING.md # Order processing
+├── STRUCTURE.md # System architecture
+├── LOGGING.md # Logging practices
+├── SALESFORCE-PRODUCTS.md # SF configuration
+└── PORTAL-ROADMAP.md # Future plans
```
-## 🔧 Development Workflow
+## 🎯 Key Principles
-### Environment Setup
+### Clean Documentation
+- ✅ **Single source of truth** - No redundant docs
+- ✅ **Up-to-date** - Reflects current implementation
+- ✅ **Practical** - Includes real code examples
+- ✅ **Organized** - Clear structure and navigation
-- **Environment-specific templates**: `.env.dev.example` or `.env.production.example`
-- **Development database**: PostgreSQL in Docker
-- **Cache**: Redis in Docker
-- **Apps**: Run locally with hot reload
+### Developer Experience
+- ✅ **Quick reference** - Essential info easily accessible
+- ✅ **Complete examples** - Working code snippets
+- ✅ **Troubleshooting** - Common issues and solutions
+- ✅ **Testing guidance** - How to verify implementations
-### Commands
+---
-```bash
-# Development
-pnpm dev:start # Start services
-pnpm dev:apps # Start services + apps
-pnpm dev:tools # Start with admin tools
-pnpm dev:migrate # Run migrations
-pnpm dev:reset # Reset environment
-
-# Production
-pnpm prod:deploy # Full deployment
-pnpm prod:update # Update deployment
-pnpm prod:status # Health checks
-pnpm prod:backup # Database backup
-```
-
-## 🚀 Production Deployment
-
-### Docker Production Stack
-
-- **Frontend**: Next.js in optimized container
-- **Backend**: NestJS in optimized container
-- **Database**: PostgreSQL with performance tuning
-- **Cache**: Redis with production config
-- **Health checks**: Built-in monitoring
-- **Security**: Non-root containers, proper networking
-
-### Plesk Integration
-
-1. **Update Plesk Git action** to use: `./scripts/plesk-deploy.sh`
-2. **Configure environment**: Create `.env` from template
-3. **Deploy**: Push to GitHub triggers automatic deployment
-
-## 🔍 Key Features
-
-### Development
-
-- ✅ **Fast startup**: Services in containers, apps local
-- ✅ **Hot reload**: Full debugging and development tools
-- ✅ **Admin tools**: Database and Redis management
-- ✅ **Clean separation**: No production configs mixed in
-
-### Production
-
-- ✅ **Enterprise-grade**: Complete containerization
-- ✅ **Performance optimized**: Tuned PostgreSQL + Redis
-- ✅ **Security hardened**: Non-root users, health checks
-- ✅ **Zero-downtime**: Rolling updates supported
-- ✅ **Monitoring ready**: Built-in health endpoints
-
-### Architecture
-
-- ✅ **BFF Pattern**: Backend for Frontend with NestJS
-- ✅ **Type Safety**: Shared TypeScript types
-- ✅ **Modern Stack**: Next.js 15, React 19, PostgreSQL, Redis
-- ✅ **Monorepo**: PNPM workspaces for code sharing
-
-## 🔐 Security & Best Practices
-
-- **Environment isolation**: Clear dev/prod separation
-- **Secret management**: Secure key storage
-- **Container security**: Non-root users, minimal images
-- **Database security**: Connection pooling, prepared statements
-- **API security**: JWT authentication, CORS protection
-
-## 📊 Monitoring & Logging
-
-- **Health checks**: All services have health endpoints
-- **Structured logging**: JSON logs in production
-- **Performance monitoring**: Built-in metrics
-- **Error tracking**: Comprehensive error handling
-
-## 🎯 Clean Structure Benefits
-
-- ✅ **No duplicates**: Single source of truth
-- ✅ **No clutter**: Only necessary files
-- ✅ **Clear organization**: Intuitive directory structure
-- ✅ **Easy onboarding**: Self-explanatory setup
-- ✅ **Professional**: Enterprise best practices
-
-This setup provides **enterprise-grade deployment** with **developer-friendly workflows**! 🚀
+*This documentation reflects the current clean, modern implementation of the Customer Portal system.*
diff --git a/docs/SERVICE-REFACTOR-GUIDE.md b/docs/SERVICE-REFACTOR-GUIDE.md
deleted file mode 100644
index 2ffb1a45..00000000
--- a/docs/SERVICE-REFACTOR-GUIDE.md
+++ /dev/null
@@ -1,273 +0,0 @@
-# Service Refactoring Guide: Modular Architecture
-
-## 🎯 **Problem Solved: Monolithic Services**
-
-### ❌ **Before: Monolithic Structure**
-```typescript
-// CatalogService.ts (700+ lines)
-class CatalogService {
- // Internet logic mixed with SIM logic mixed with VPN logic
- // Caching logic mixed with business logic
- // Hard to test, maintain, and extend
-}
-
-// OrdersService.ts (400+ lines)
-class OrdersService {
- // Validation, building, item creation, provisioning all mixed
- // Difficult to isolate specific functionality
-}
-```
-
-**Problems:**
-- ❌ Single Responsibility Principle violated
-- ❌ Hard to test individual components
-- ❌ Difficult to maintain and debug
-- ❌ High coupling between unrelated logic
-- ❌ Large classes with mixed concerns
-
-## ✅ **After: Modular Architecture**
-
-### **🏗️ Catalog Services Structure**
-
-```
-📁 catalog/
-├── 📁 services/
-│ ├── base-catalog.service.ts # 🔧 Common Salesforce operations
-│ ├── internet-catalog.service.ts # 🌐 Internet-specific logic
-│ ├── sim-catalog.service.ts # 📱 SIM-specific logic
-│ ├── vpn-catalog.service.ts # 🔒 VPN-specific logic
-│ └── catalog-orchestrator.service.ts # 🎯 Coordinates everything + caching
-├── catalog.controller.ts # 🚀 Routes to orchestrator
-├── catalog.service.ts # ⚡ Legacy (backward compatible)
-└── structured-catalog.service.ts # ⚡ Legacy (backward compatible)
-```
-
-### **🏗️ Orders Services Structure**
-
-```
-📁 orders/
-├── 📁 services/
-│ ├── order-validator.service.ts # ✅ Validation logic only
-│ ├── order-builder.service.ts # 🔨 Order header building
-│ ├── order-item-builder.service.ts # 📦 OrderItem creation
-│ └── order-orchestrator.service.ts # 🎯 Coordinates order flow
-├── orders.controller.ts # 🚀 Routes to orchestrator
-└── orders.service.ts # ⚡ Legacy (backward compatible)
-```
-
-## 🧩 **Service Responsibilities**
-
-### **Catalog Services**
-
-| Service | Responsibility | Lines | Dependencies |
-|---------|---------------|-------|-------------|
-| `BaseCatalogService` | Common Salesforce queries, field mapping, error handling | ~120 | SF, Logger |
-| `InternetCatalogService` | Internet plans, installations, add-ons logic | ~180 | BaseCatalog |
-| `SimCatalogService` | SIM plans, activation fees, add-ons logic | ~140 | BaseCatalog |
-| `VpnCatalogService` | VPN plans, activation fees logic | ~100 | BaseCatalog |
-| `CatalogOrchestrator` | Coordinates services, handles caching | ~120 | All catalog services |
-
-### **Order Services**
-
-| Service | Responsibility | Lines | Dependencies |
-|---------|---------------|-------|-------------|
-| `OrderValidator` | Business rule validation, user mapping | ~180 | Mappings, WHMCS, SF |
-| `OrderBuilder` | Order header field building | ~90 | None |
-| `OrderItemBuilder` | SKU parsing, OrderItem creation | ~160 | SF |
-| `OrderOrchestrator` | Coordinates order creation flow | ~120 | All order services |
-
-## 🎯 **Usage Examples**
-
-### **Using New Catalog Architecture**
-```typescript
-// In your service/controller
-constructor(
- private catalogOrchestrator: CatalogOrchestrator,
- private internetCatalog: InternetCatalogService
-) {}
-
-// Get complete structured catalog (cached)
-const catalog = await this.catalogOrchestrator.getStructuredCatalog();
-
-// Get only Internet data (cached)
-const internetData = await this.catalogOrchestrator.getInternetCatalog();
-
-// Get specific Internet plans directly
-const plans = await this.internetCatalog.getPlans();
-```
-
-### **Using New Order Architecture**
-```typescript
-// In your controller
-constructor(private orderOrchestrator: OrderOrchestrator) {}
-
-// Create order using orchestrated flow
-const result = await this.orderOrchestrator.createOrder(userId, orderData);
-
-// Get user orders
-const orders = await this.orderOrchestrator.getOrdersForUser(userId);
-```
-
-### **Testing Individual Components**
-```typescript
-// Test only Internet catalog logic
-describe('InternetCatalogService', () => {
- let service: InternetCatalogService;
- let mockBaseCatalog: jest.Mocked;
-
- beforeEach(() => {
- const module = Test.createTestingModule({
- providers: [
- InternetCatalogService,
- { provide: BaseCatalogService, useValue: mockBaseCatalog }
- ]
- });
- service = module.get(InternetCatalogService);
- });
-
- it('should parse internet plans correctly', async () => {
- // Test only internet-specific logic, isolated
- });
-});
-```
-
-## 🔄 **Backward Compatibility**
-
-### **Clean API Endpoints**
-```typescript
-// ✅ Clean architecture endpoints
-GET /api/catalog // Uses CatalogOrchestrator (legacy format)
-GET /api/catalog/structured // Uses CatalogOrchestrator (recommended)
-GET /api/catalog/internet/addons // Uses CatalogOrchestrator
-
-// ✅ Clean order endpoints
-POST /api/orders // Uses OrderOrchestrator
-GET /api/orders/user // Uses OrderOrchestrator
-GET /api/orders/:id // Uses OrderOrchestrator
-```
-
-### **Clean Architecture Implementation**
-```typescript
-// ✅ Final clean implementation - no legacy code
-@Module({
- providers: [
- BaseCatalogService, // Common operations
- CatalogOrchestrator, // Main coordinator
- InternetCatalogService, // Focused responsibility
- SimCatalogService, // Focused responsibility
- VpnCatalogService, // Focused responsibility
- ]
-})
-
-// ✅ Controller uses only orchestrator
-@Controller()
-class CatalogController {
- constructor(
- private catalogOrchestrator: CatalogOrchestrator // Single clean interface
- ) {}
-
- @Get() getCatalog() { return this.catalogOrchestrator.getLegacyCatalog(); }
- @Get('structured') getStructured() { return this.catalogOrchestrator.getStructuredCatalog(); }
-}
-```
-
-## 📊 **Benefits Achieved**
-
-| Aspect | Before | After |
-|--------|---------|--------|
-| **Service Size** | 700+ lines | ~120 lines per service |
-| **Testability** | Hard (monolithic) | Easy (focused) |
-| **Maintainability** | Difficult (mixed concerns) | Simple (single responsibility) |
-| **Performance** | No specialized caching | Service-specific caching |
-| **Extensibility** | Break existing code | Add new services cleanly |
-| **Debugging** | Search through 700+ lines | Check specific 120-line service |
-| **Code Coupling** | High (everything connected) | Low (focused dependencies) |
-
-## 🚀 **Extension Examples**
-
-### **Adding New Product Type**
-```typescript
-// 1. Create focused service
-@Injectable()
-export class IotCatalogService extends BaseCatalogService {
- async getDevices(): Promise {
- const soql = this.buildCatalogServiceQuery('IoT');
- // IoT-specific logic only, ~100 lines
- }
-}
-
-// 2. Add to orchestrator
-@Injectable()
-export class CatalogOrchestrator {
- constructor(
- // ... existing services
- private iotCatalog: IotCatalogService // Add new service
- ) {}
-
- async getStructuredCatalog() {
- const [internet, sim, vpn, iot] = await Promise.all([
- this.internetCatalog.getCatalogData(),
- this.simCatalog.getCatalogData(),
- this.vpnCatalog.getCatalogData(),
- this.iotCatalog.getCatalogData() // Add new data
- ]);
-
- return { internet, sim, vpn, iot };
- }
-}
-
-// 3. Zero changes to existing services! 🎉
-```
-
-### **Adding New Order Validation**
-```typescript
-// Add to OrderValidator - single responsibility
-@Injectable()
-export class OrderValidator {
- validateCreditCheck(orderData: any): void {
- // Add new validation logic without touching other services
- }
-}
-
-// OrderOrchestrator automatically uses new validation
-// No changes needed elsewhere! 🎉
-```
-
-## 🔧 **Development Benefits**
-
-### **Focused Development**
-```typescript
-// Working on Internet features? Only touch InternetCatalogService
-// Working on order validation? Only touch OrderValidator
-// Working on caching? Only touch CatalogOrchestrator
-```
-
-### **Easy Testing**
-```typescript
-// Test only what you're working on
-describe('InternetCatalogService', () => {
- // Mock only BaseCatalogService
- // Test only Internet logic
- // ~50 test lines vs 200+ before
-});
-```
-
-### **Clear Code Ownership**
-```typescript
-// 🌐 Internet features → InternetCatalogService
-// 📱 SIM features → SimCatalogService
-// 🔒 VPN features → VpnCatalogService
-// ✅ Order validation → OrderValidator
-// 📦 Order items → OrderItemBuilder
-```
-
-## 🎯 **Implementation Complete**
-
-✅ **Clean Architecture Achieved:**
-1. **Modular services** with single responsibilities
-2. **Shared types** eliminating duplication
-3. **Reusable utilities** for business logic
-4. **Clean API endpoints** using orchestrators
-5. **Easy testing** with focused components
-
-The clean architecture provides excellent maintainability, testability, and extensibility! 🎉
diff --git a/docs/STRUCTURED-CATALOG-EXAMPLE.md b/docs/STRUCTURED-CATALOG-EXAMPLE.md
deleted file mode 100644
index 22591301..00000000
--- a/docs/STRUCTURED-CATALOG-EXAMPLE.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# Structured Catalog Architecture - Frontend Example
-
-## ❌ **OLD WAY (Bad)**: Name Matching in Frontend
-
-```typescript
-// WRONG: Frontend doing business logic and name matching
-const [plans, setPlans] = useState([]);
-
-// Bad API call - flat structure requiring guesswork
-const catalog = await api.get<{internet: InternetPlan[]}>("/catalog");
-
-// Terrible: Guessing product types by name matching
-const isSilver = plan.name?.toLowerCase().includes('silver');
-const isGold = plan.name?.toLowerCase().includes('gold');
-const isPlatinum = plan.name?.toLowerCase().includes('platinum');
-
-// Bad: SKU parsing in frontend
-const hikariService = addons.find(addon =>
- addon.sku.includes('HOME-PHONE') || addon.sku.includes('HIKARI-DENWA')
-);
-
-// Bad: Installation type guessing
-const installationProduct = installations.find(inst =>
- inst.sku.toLowerCase().includes('12') ||
- inst.name.toLowerCase().includes('12')
-);
-
-// Frontend doing business logic it shouldn't
-{isSilver && (
-