refactor(bff): restructure service architecture with clearer naming conventions

- Rename integration orchestrators to facades:
  - WhmcsConnectionOrchestratorService → WhmcsConnectionFacade
  - FreebitOperationsService → FreebitFacade
  - SalesforceService → SalesforceFacade

- Rename module orchestrator:
  - SimOrchestratorService → SimOrchestrator

- Rename aggregators for clarity:
  - MeStatusService → MeStatusAggregator
  - UserProfileService → UserProfileAggregator

- Move integration facades to dedicated facades/ folders:
  - whmcs/facades/whmcs.facade.ts
  - salesforce/facades/salesforce.facade.ts
  - freebit/facades/freebit.facade.ts

This establishes clearer architectural boundaries between:
- Facades: unified entry points for integration subsystems
- Orchestrators: coordinate workflows across multiple services
- Aggregators: read-only data composition from multiple sources

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/bff/src/integrations/freebit/facades/freebit.facade.ts

@@ -1,23 +1,24 @@
 import { Injectable } from "@nestjs/common";
-import { FreebitAccountService } from "./freebit-account.service.js";
+import { FreebitAccountService } from "../services/freebit-account.service.js";
-import { FreebitUsageService } from "./freebit-usage.service.js";
+import { FreebitUsageService } from "../services/freebit-usage.service.js";
-import { FreebitPlanService } from "./freebit-plan.service.js";
+import { FreebitPlanService } from "../services/freebit-plan.service.js";
-import { FreebitVoiceService } from "./freebit-voice.service.js";
+import { FreebitVoiceService } from "../services/freebit-voice.service.js";
-import { FreebitCancellationService } from "./freebit-cancellation.service.js";
+import { FreebitCancellationService } from "../services/freebit-cancellation.service.js";
-import { FreebitEsimService, type EsimActivationParams } from "./freebit-esim.service.js";
+import { FreebitEsimService, type EsimActivationParams } from "../services/freebit-esim.service.js";
-import { FreebitMapperService } from "./freebit-mapper.service.js";
+import { FreebitMapperService } from "../services/freebit-mapper.service.js";
 import type { SimDetails, SimUsage, SimTopUpHistory } from "../interfaces/freebit.types.js";
 
 /**
- * Freebit Operations Facade
+ * Freebit Facade
  *
- * Unified interface for all Freebit SIM operations.
+ * Unified entry point for all Freebit SIM operations.
  * Delegates to specialized services for each operation type.
  *
- * This service handles account normalization automatically, so consumers
+ * This facade handles account normalization automatically, so consumers
  * don't need to worry about formatting phone numbers correctly.
  *
- * Services:
+ * @remarks
+ * Specialized services:
  * - FreebitAccountService: SIM details, health checks
  * - FreebitUsageService: Usage queries, top-ups, quota history
  * - FreebitPlanService: Plan changes (PA05-21)
@@ -26,7 +27,7 @@ import type { SimDetails, SimUsage, SimTopUpHistory } from "../interfaces/freebi
  * - FreebitEsimService: eSIM profile management
  */
 @Injectable()
-export class FreebitOperationsService {
+export class FreebitFacade {
   constructor(
     private readonly accountService: FreebitAccountService,
     private readonly usageService: FreebitUsageService,

apps/bff/src/integrations/freebit/freebit.module.ts

@@ -1,6 +1,6 @@
 import { Module } from "@nestjs/common";
 import { FreebitMapperService } from "./services/freebit-mapper.service.js";
-import { FreebitOperationsService } from "./services/freebit-operations.service.js";
+import { FreebitFacade } from "./facades/freebit.facade.js";
 import { FreebitClientService } from "./services/freebit-client.service.js";
 import { FreebitAuthService } from "./services/freebit-auth.service.js";
 import { FreebitRateLimiterService } from "./services/freebit-rate-limiter.service.js";
@@ -30,13 +30,13 @@ import { VoiceOptionsModule } from "../../modules/voice-options/voice-options.mo
     FreebitCancellationService,
     FreebitEsimService,
     // Facade (delegates to specialized services, handles account normalization)
-    FreebitOperationsService,
+    FreebitFacade,
   ],
   exports: [
     // Export error handler
     FreebitErrorHandlerService,
     // Export main facade for all Freebit operations
-    FreebitOperationsService,
+    FreebitFacade,
     // Export specialized services for direct access if needed
     FreebitAccountService,
     FreebitUsageService,

apps/bff/src/integrations/freebit/services/index.ts

@@ -1,6 +1,6 @@
 // Export all Freebit services
 export { FreebitMapperService } from "./freebit-mapper.service.js";
-export { FreebitOperationsService } from "./freebit-operations.service.js";
+export { FreebitFacade } from "../facades/freebit.facade.js";
 export { FreebitRateLimiterService } from "./freebit-rate-limiter.service.js";
 export { FreebitAccountService } from "./freebit-account.service.js";
 export { FreebitUsageService } from "./freebit-usage.service.js";

apps/bff/src/integrations/salesforce/facades/salesforce.facade.ts

@@ -3,19 +3,22 @@ import type { OnModuleInit } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ConfigService } from "@nestjs/config";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
-import { SalesforceConnection } from "./services/salesforce-connection.service.js";
+import { SalesforceConnection } from "../services/salesforce-connection.service.js";
 import {
   SalesforceAccountService,
   type SalesforceAccountPortalUpdate,
   type UpdateSalesforceContactAddressRequest,
-} from "./services/salesforce-account.service.js";
+} from "../services/salesforce-account.service.js";
 import { SalesforceOperationException } from "@bff/core/exceptions/domain-exceptions.js";
 import type { SalesforceOrderRecord } from "@customer-portal/domain/orders/providers";
 
 /**
- * Salesforce Service - Facade for Salesforce operations
+ * Salesforce Facade
  *
- * Account Methods (Actually Used):
+ * Unified entry point for Salesforce operations used across the BFF.
+ *
+ * @remarks
+ * Account Methods:
  * - findAccountByCustomerNumber() - Used in signup/WHMCS linking workflows
  * - getAccountDetails() - Used in signup to check WH_Account__c field
  *
@@ -23,10 +26,10 @@ import type { SalesforceOrderRecord } from "@customer-portal/domain/orders/provi
  * - updateOrder() - Used in order provisioning
  * - getOrder() - Used to fetch order details
  *
- * Note: Internet Eligibility checking happens in internet-catalog.service.ts
+ * Note: For complex queries, use specialized services (SalesforceOrderService, etc.)
  */
 @Injectable()
-export class SalesforceService implements OnModuleInit {
+export class SalesforceFacade implements OnModuleInit {
   constructor(
     private configService: ConfigService,
     private connection: SalesforceConnection,

apps/bff/src/integrations/salesforce/salesforce.module.ts

@@ -1,7 +1,7 @@
 import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { QueueModule } from "@bff/infra/queue/queue.module.js";
-import { SalesforceService } from "./salesforce.service.js";
+import { SalesforceFacade } from "./facades/salesforce.facade.js";
 import { SalesforceConnection } from "./services/salesforce-connection.service.js";
 import { SalesforceAccountService } from "./services/salesforce-account.service.js";
 import { SalesforceOrderService } from "./services/salesforce-order.service.js";
@@ -31,14 +31,14 @@ import { SalesforceErrorHandlerService } from "./services/salesforce-error-handl
     // Opportunity facade (depends on decomposed services)
     SalesforceOpportunityService,
     OpportunityResolutionService,
-    SalesforceService,
+    SalesforceFacade,
     SalesforceReadThrottleGuard,
     SalesforceWriteThrottleGuard,
   ],
   exports: [
     QueueModule,
     SalesforceErrorHandlerService,
-    SalesforceService,
+    SalesforceFacade,
     SalesforceConnection,
     SalesforceAccountService,
     SalesforceOrderService,

apps/bff/src/integrations/whmcs/facades/whmcs.facade.ts

@@ -2,9 +2,9 @@ import { Injectable, Inject } from "@nestjs/common";
 import type { OnModuleInit } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
-import { WhmcsConfigService } from "../config/whmcs-config.service.js";
+import { WhmcsConfigService } from "../connection/config/whmcs-config.service.js";
-import { WhmcsHttpClientService } from "./whmcs-http-client.service.js";
+import { WhmcsHttpClientService } from "../connection/services/whmcs-http-client.service.js";
-import { WhmcsErrorHandlerService } from "./whmcs-error-handler.service.js";
+import { WhmcsErrorHandlerService } from "../connection/services/whmcs-error-handler.service.js";
 import { WhmcsRequestQueueService } from "@bff/infra/queue/services/whmcs-request-queue.service.js";
 import type {
   WhmcsAddClientParams,
@@ -37,14 +37,23 @@ import type {
 } from "@customer-portal/domain/subscriptions/providers";
 import type { WhmcsCatalogProductListResponse } from "@customer-portal/domain/services/providers";
 import type { WhmcsErrorResponse } from "@customer-portal/domain/common/providers";
-import type { WhmcsRequestOptions, WhmcsConnectionStats } from "../types/connection.types.js";
+import type {
+  WhmcsRequestOptions,
+  WhmcsConnectionStats,
+} from "../connection/types/connection.types.js";
 
 /**
- * Main orchestrator service for WHMCS connections
+ * WHMCS Connection Facade
- * Single path for all WHMCS requests with queue management and error handling
+ *
+ * Single entry point for all WHMCS API operations.
+ * Provides unified interface with queue management, error handling, and request prioritization.
+ *
+ * @remarks
+ * All WHMCS entity services (Invoice, Client, Subscription, etc.) delegate to this facade
+ * for actual API communication. This ensures consistent error handling and rate limiting.
  */
 @Injectable()
-export class WhmcsConnectionOrchestratorService implements OnModuleInit {
+export class WhmcsConnectionFacade implements OnModuleInit {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
     private readonly configService: WhmcsConfigService,

apps/bff/src/integrations/whmcs/services/whmcs-account-discovery.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, NotFoundException, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { WhmcsCacheService } from "../cache/whmcs-cache.service.js";
 import { transformWhmcsClientResponse } from "@customer-portal/domain/customer/providers";
 import type { WhmcsClient } from "@customer-portal/domain/customer";
@@ -13,7 +13,7 @@ import type { WhmcsClient } from "@customer-portal/domain/customer";
 @Injectable()
 export class WhmcsAccountDiscoveryService {
   constructor(
-    private readonly connectionService: WhmcsConnectionOrchestratorService,
+    private readonly connectionService: WhmcsConnectionFacade,
     private readonly cacheService: WhmcsCacheService,
     @Inject(Logger) private readonly logger: Logger
   ) {}

apps/bff/src/integrations/whmcs/services/whmcs-client.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, NotFoundException, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { WhmcsCacheService } from "../cache/whmcs-cache.service.js";
 import type {
   WhmcsValidateLoginParams,
@@ -19,7 +19,7 @@ import { addressSchema, type Address, type WhmcsClient } from "@customer-portal/
 @Injectable()
 export class WhmcsClientService {
   constructor(
-    private readonly connectionService: WhmcsConnectionOrchestratorService,
+    private readonly connectionService: WhmcsConnectionFacade,
     private readonly cacheService: WhmcsCacheService,
     @Inject(Logger) private readonly logger: Logger
   ) {}

apps/bff/src/integrations/whmcs/services/whmcs-currency.service.ts

@@ -3,7 +3,7 @@ import type { OnModuleInit, OnModuleDestroy } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { WhmcsOperationException } from "@bff/core/exceptions/domain-exceptions.js";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { FALLBACK_CURRENCY } from "@customer-portal/domain/billing";
 import type { Currency } from "@customer-portal/domain/billing";
 import type { WhmcsCurrenciesResponse } from "@customer-portal/domain/billing/providers";
@@ -17,7 +17,7 @@ export class WhmcsCurrencyService implements OnModuleInit, OnModuleDestroy {
 
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly connectionService: WhmcsConnectionOrchestratorService
+    private readonly connectionService: WhmcsConnectionFacade
   ) {}
 
   async onModuleInit() {

apps/bff/src/integrations/whmcs/services/whmcs-invoice.service.ts

@@ -6,7 +6,7 @@ import { WhmcsOperationException } from "@bff/core/exceptions/domain-exceptions.
 import { invoiceListSchema, invoiceSchema } from "@customer-portal/domain/billing";
 import type { Invoice, InvoiceList } from "@customer-portal/domain/billing";
 import { transformWhmcsInvoice } from "@customer-portal/domain/billing/providers";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { WhmcsCurrencyService } from "./whmcs-currency.service.js";
 import { WhmcsCacheService } from "../cache/whmcs-cache.service.js";
 import type {
@@ -31,7 +31,7 @@ export type InvoiceFilters = Partial<{
 export class WhmcsInvoiceService {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly connectionService: WhmcsConnectionOrchestratorService,
+    private readonly connectionService: WhmcsConnectionFacade,
     private readonly currencyService: WhmcsCurrencyService,
     private readonly cacheService: WhmcsCacheService
   ) {}

apps/bff/src/integrations/whmcs/services/whmcs-order.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { WhmcsOperationException } from "@bff/core/exceptions/domain-exceptions.js";
 
@@ -21,7 +21,7 @@ export type { WhmcsOrderItem, WhmcsAddOrderParams, WhmcsOrderResult };
 @Injectable()
 export class WhmcsOrderService {
   constructor(
-    private readonly connection: WhmcsConnectionOrchestratorService,
+    private readonly connection: WhmcsConnectionFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts

@@ -13,7 +13,7 @@ import type {
 } from "@customer-portal/domain/payments";
 import type { WhmcsCatalogProductNormalized } from "@customer-portal/domain/services/providers";
 import { transformWhmcsCatalogProductsResponse } from "@customer-portal/domain/services/providers";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { WhmcsCacheService } from "../cache/whmcs-cache.service.js";
 import type { WhmcsCreateSsoTokenParams } from "@customer-portal/domain/customer/providers";
 import type {
@@ -28,7 +28,7 @@ import type {
 export class WhmcsPaymentService {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly connectionService: WhmcsConnectionOrchestratorService,
+    private readonly connectionService: WhmcsConnectionFacade,
     private readonly cacheService: WhmcsCacheService
   ) {}
 

apps/bff/src/integrations/whmcs/services/whmcs-sso.service.ts

@@ -1,7 +1,7 @@
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { Logger } from "nestjs-pino";
 import { Injectable, Inject } from "@nestjs/common";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import type {
   WhmcsCreateSsoTokenParams,
   WhmcsSsoResponse,
@@ -11,7 +11,7 @@ import type {
 export class WhmcsSsoService {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly connectionService: WhmcsConnectionOrchestratorService
+    private readonly connectionService: WhmcsConnectionFacade
   ) {}
 
   /**

apps/bff/src/integrations/whmcs/services/whmcs-subscription.service.ts

@@ -7,7 +7,7 @@ import {
   transformWhmcsSubscriptionListResponse,
 } from "@customer-portal/domain/subscriptions/providers";
 import type { Subscription, SubscriptionList } from "@customer-portal/domain/subscriptions";
-import { WhmcsConnectionOrchestratorService } from "../connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "../facades/whmcs.facade.js";
 import { WhmcsCurrencyService } from "./whmcs-currency.service.js";
 import { WhmcsCacheService } from "../cache/whmcs-cache.service.js";
 import type { WhmcsGetClientsProductsParams } from "@customer-portal/domain/subscriptions/providers";
@@ -20,7 +20,7 @@ export interface SubscriptionFilters {
 export class WhmcsSubscriptionService {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly connectionService: WhmcsConnectionOrchestratorService,
+    private readonly connectionService: WhmcsConnectionFacade,
     private readonly currencyService: WhmcsCurrencyService,
     private readonly cacheService: WhmcsCacheService
   ) {}

apps/bff/src/integrations/whmcs/whmcs.module.ts

@@ -11,7 +11,7 @@ import { WhmcsOrderService } from "./services/whmcs-order.service.js";
 import { WhmcsCurrencyService } from "./services/whmcs-currency.service.js";
 import { WhmcsAccountDiscoveryService } from "./services/whmcs-account-discovery.service.js";
 // Connection services
-import { WhmcsConnectionOrchestratorService } from "./connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "./facades/whmcs.facade.js";
 import { WhmcsConfigService } from "./connection/config/whmcs-config.service.js";
 import { WhmcsHttpClientService } from "./connection/services/whmcs-http-client.service.js";
 import { WhmcsErrorHandlerService } from "./connection/services/whmcs-error-handler.service.js";
@@ -19,8 +19,8 @@ import { WhmcsErrorHandlerService } from "./connection/services/whmcs-error-hand
 @Module({
   imports: [ConfigModule, QueueModule],
   providers: [
-    // Connection services (single path: orchestrator → httpClient)
+    // Connection facade (single path: facade → httpClient)
-    WhmcsConnectionOrchestratorService,
+    WhmcsConnectionFacade,
     WhmcsConfigService,
     WhmcsHttpClientService,
     WhmcsErrorHandlerService,
@@ -36,7 +36,7 @@ import { WhmcsErrorHandlerService } from "./connection/services/whmcs-error-hand
     WhmcsAccountDiscoveryService,
   ],
   exports: [
-    WhmcsConnectionOrchestratorService,
+    WhmcsConnectionFacade,
     WhmcsCacheService,
     WhmcsClientService,
     WhmcsOrderService,

apps/bff/src/modules/auth/application/auth-health.service.ts

@@ -5,8 +5,8 @@ import { Injectable, Inject } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { Logger } from "nestjs-pino";
 import { UsersFacade } from "@bff/modules/users/application/users.facade.js";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 
 export interface AuthHealthCheckResult {
@@ -32,8 +32,8 @@ export class AuthHealthService {
   constructor(
     private readonly usersFacade: UsersFacade,
     private readonly configService: ConfigService,
-    private readonly whmcsConnectionService: WhmcsConnectionOrchestratorService,
+    private readonly whmcsConnectionService: WhmcsConnectionFacade,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/modules/auth/application/auth.facade.ts

@@ -3,7 +3,7 @@ import { UsersFacade } from "@bff/modules/users/application/users.facade.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { WhmcsAccountDiscoveryService } from "@bff/integrations/whmcs/services/whmcs-account-discovery.service.js";
 import { WhmcsSsoService } from "@bff/integrations/whmcs/services/whmcs-sso.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { AuditService, AuditAction } from "@bff/infra/audit/audit.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { Logger } from "nestjs-pino";
@@ -47,7 +47,7 @@ export class AuthFacade {
     private readonly mappingsService: MappingsService,
     private readonly whmcsSsoService: WhmcsSsoService,
     private readonly discoveryService: WhmcsAccountDiscoveryService,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly auditService: AuditService,
     private readonly tokenBlacklistService: TokenBlacklistService,
     private readonly signupWorkflow: SignupWorkflowService,

apps/bff/src/modules/auth/infra/workflows/get-started-workflow.service.ts

@@ -42,7 +42,7 @@ import {
   PORTAL_STATUS_ACTIVE,
   PORTAL_STATUS_NOT_YET,
 } from "@bff/modules/auth/constants/portal.constants.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 
 /**
  * Remove undefined properties from an object (for exactOptionalPropertyTypes compatibility)
@@ -74,7 +74,7 @@ export class GetStartedWorkflowService {
     private readonly mappingsService: MappingsService,
     private readonly auditService: AuditService,
     private readonly salesforceAccountService: SalesforceAccountService,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly opportunityResolution: OpportunityResolutionService,
     private readonly workflowCases: WorkflowCaseManager,
     private readonly whmcsDiscovery: WhmcsAccountDiscoveryService,

apps/bff/src/modules/auth/infra/workflows/signup-workflow.service.ts

@@ -5,7 +5,7 @@ import type { Request } from "express";
 import { AuditService, AuditAction } from "@bff/infra/audit/audit.service.js";
 import { UsersFacade } from "@bff/modules/users/application/users.facade.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { AuthTokenService } from "../token/token.service.js";
 import { AuthRateLimitService } from "../rate-limiting/auth-rate-limit.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
@@ -42,7 +42,7 @@ export class SignupWorkflowService {
   constructor(
     private readonly usersFacade: UsersFacade,
     private readonly mappingsService: MappingsService,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly auditService: AuditService,
     private readonly tokenService: AuthTokenService,
     private readonly authRateLimitService: AuthRateLimitService,

apps/bff/src/modules/auth/infra/workflows/signup/signup-account-resolver.service.ts

@@ -4,7 +4,7 @@
 import { Injectable, Inject, BadRequestException, ConflictException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { CacheService } from "@bff/infra/cache/cache.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { SalesforceAccountService } from "@bff/integrations/salesforce/services/salesforce-account.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import type { SignupRequest } from "@customer-portal/domain/auth";
@@ -17,7 +17,7 @@ export class SignupAccountResolverService {
   private readonly cachePrefix = "auth:signup:account:";
 
   constructor(
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly salesforceAccountService: SalesforceAccountService,
     private readonly cache: CacheService,
     @Inject(Logger) private readonly logger: Logger

apps/bff/src/modules/auth/infra/workflows/whmcs-link-workflow.service.ts

@@ -10,7 +10,7 @@ import { UsersFacade } from "@bff/modules/users/application/users.facade.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { WhmcsAccountDiscoveryService } from "@bff/integrations/whmcs/services/whmcs-account-discovery.service.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { mapPrismaUserToDomain } from "@bff/infra/mappers/index.js";
 import { getCustomFieldValue } from "@customer-portal/domain/customer/providers";
@@ -28,7 +28,7 @@ export class WhmcsLinkWorkflowService {
     private readonly mappingsService: MappingsService,
     private readonly whmcsClientService: WhmcsClientService,
     private readonly discoveryService: WhmcsAccountDiscoveryService,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/modules/me-status/me-status.controller.ts

@@ -1,12 +1,12 @@
 import { Controller, Get, Req, UseGuards } from "@nestjs/common";
 import type { RequestWithUser } from "@bff/modules/auth/auth.types.js";
 import { SalesforceReadThrottleGuard } from "@bff/integrations/salesforce/guards/salesforce-read-throttle.guard.js";
-import { MeStatusService } from "./me-status.service.js";
+import { MeStatusAggregator } from "./me-status.service.js";
 import type { MeStatus } from "@customer-portal/domain/dashboard";
 
 @Controller("me")
 export class MeStatusController {
-  constructor(private readonly meStatus: MeStatusService) {}
+  constructor(private readonly meStatus: MeStatusAggregator) {}
 
   @UseGuards(SalesforceReadThrottleGuard)
   @Get("status")

apps/bff/src/modules/me-status/me-status.module.ts

@@ -1,6 +1,6 @@
 import { Module } from "@nestjs/common";
 import { MeStatusController } from "./me-status.controller.js";
-import { MeStatusService } from "./me-status.service.js";
+import { MeStatusAggregator } from "./me-status.service.js";
 import { UsersModule } from "@bff/modules/users/users.module.js";
 import { OrdersModule } from "@bff/modules/orders/orders.module.js";
 import { ServicesModule } from "@bff/modules/services/services.module.js";
@@ -22,6 +22,6 @@ import { SalesforceModule } from "@bff/integrations/salesforce/salesforce.module
     SalesforceModule,
   ],
   controllers: [MeStatusController],
-  providers: [MeStatusService],
+  providers: [MeStatusAggregator],
 })
 export class MeStatusModule {}

apps/bff/src/modules/me-status/me-status.service.ts

@@ -22,8 +22,15 @@ import {
 } from "@customer-portal/domain/customer";
 import type { OrderSummary } from "@customer-portal/domain/orders";
 
+/**
+ * Me Status Aggregator
+ *
+ * Read-only aggregator that combines data from multiple sources
+ * (users, orders, eligibility, verification, payments, notifications)
+ * to build the dashboard status response.
+ */
 @Injectable()
-export class MeStatusService {
+export class MeStatusAggregator {
   constructor(
     private readonly users: UsersFacade,
     private readonly orders: OrderOrchestrator,

apps/bff/src/modules/orders/queue/provisioning.processor.ts

@@ -2,7 +2,7 @@ import { Processor, WorkerHost } from "@nestjs/bullmq";
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { OrderFulfillmentOrchestrator } from "../services/order-fulfillment-orchestrator.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import type { ProvisioningJobData } from "./provisioning.queue.js";
 import { QUEUE_NAMES } from "@bff/infra/queue/queue.constants.js";
 
@@ -11,7 +11,7 @@ import { QUEUE_NAMES } from "@bff/infra/queue/queue.constants.js";
 export class ProvisioningProcessor extends WorkerHost {
   constructor(
     private readonly orchestrator: OrderFulfillmentOrchestrator,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {
     super();

apps/bff/src/modules/orders/services/order-fulfillment-orchestrator.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { SalesforceOpportunityService } from "@bff/integrations/salesforce/services/salesforce-opportunity.service.js";
 import { WhmcsOrderService } from "@bff/integrations/whmcs/services/whmcs-order.service.js";
 import type { WhmcsOrderResult } from "@bff/integrations/whmcs/services/whmcs-order.service.js";
@@ -54,7 +54,7 @@ export interface OrderFulfillmentContext {
 export class OrderFulfillmentOrchestrator {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly opportunityService: SalesforceOpportunityService,
     private readonly whmcsOrderService: WhmcsOrderService,
     private readonly orderOrchestrator: OrderOrchestrator,

apps/bff/src/modules/orders/services/order-fulfillment-validator.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, BadRequestException, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { sfOrderIdParamSchema } from "@customer-portal/domain/orders";
@@ -19,7 +19,7 @@ import { PaymentValidatorService } from "./payment-validator.service.js";
 export class OrderFulfillmentValidator {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly mappingsService: MappingsService,
     private readonly paymentValidator: PaymentValidatorService
   ) {}

apps/bff/src/modules/orders/services/order-validator.service.ts

@@ -2,7 +2,7 @@ import { Injectable, BadRequestException, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ZodError } from "zod";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import {
   orderWithSkuValidationSchema,
@@ -29,7 +29,7 @@ export class OrderValidator {
   constructor(
     @Inject(Logger) private readonly logger: Logger,
     private readonly mappings: MappingsService,
-    private readonly whmcs: WhmcsConnectionOrchestratorService,
+    private readonly whmcs: WhmcsConnectionFacade,
     private readonly pricebookService: OrderPricebookService,
     private readonly simCatalogService: SimServicesService,
     private readonly internetEligibilityService: InternetEligibilityService,

apps/bff/src/modules/orders/services/payment-validator.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject, BadRequestException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 
 /**
@@ -12,7 +12,7 @@ import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 @Injectable()
 export class PaymentValidatorService {
   constructor(
-    private readonly whmcs: WhmcsConnectionOrchestratorService,
+    private readonly whmcs: WhmcsConnectionFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/modules/orders/services/sim-fulfillment.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import type { OrderDetails, OrderItemDetails } from "@customer-portal/domain/orders";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import {
@@ -16,7 +16,7 @@ export interface SimFulfillmentRequest {
 @Injectable()
 export class SimFulfillmentService {
   constructor(
-    private readonly freebit: FreebitOperationsService,
+    private readonly freebit: FreebitFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/modules/services/application/sim-services.service.ts

@@ -11,7 +11,7 @@ import { mapSimActivationFee, mapSimProduct } from "@customer-portal/domain/serv
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { SalesforceConnection } from "@bff/integrations/salesforce/services/salesforce-connection.service.js";
 import { Logger } from "nestjs-pino";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
 
 @Injectable()
 export class SimServicesService extends BaseServicesService {
@@ -20,7 +20,7 @@ export class SimServicesService extends BaseServicesService {
     configService: ConfigService,
     @Inject(Logger) logger: Logger,
     private mappingsService: MappingsService,
-    private whmcs: WhmcsConnectionOrchestratorService,
+    private whmcs: WhmcsConnectionFacade,
     private catalogCache: ServicesCacheService
   ) {
     super(sf, configService, logger);

apps/bff/src/modules/subscriptions/internet-management/services/internet-cancellation.service.ts

@@ -13,7 +13,7 @@
 
 import { Injectable, Inject, BadRequestException, NotFoundException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { SalesforceOpportunityService } from "@bff/integrations/salesforce/services/salesforce-opportunity.service.js";
@@ -37,7 +37,7 @@ import { NOTIFICATION_SOURCE, NOTIFICATION_TYPE } from "@customer-portal/domain/
 @Injectable()
 export class InternetCancellationService {
   constructor(
-    private readonly whmcsConnectionService: WhmcsConnectionOrchestratorService,
+    private readonly whmcsConnectionService: WhmcsConnectionFacade,
     private readonly whmcsClientService: WhmcsClientService,
     private readonly mappingsService: MappingsService,
     private readonly opportunityService: SalesforceOpportunityService,

apps/bff/src/modules/subscriptions/sim-management.service.ts

@@ -1,5 +1,5 @@
 import { Injectable } from "@nestjs/common";
-import { SimOrchestratorService } from "./sim-management/services/sim-orchestrator.service.js";
+import { SimOrchestrator } from "./sim-management/services/sim-orchestrator.service.js";
 import type {
   SimDetails,
   SimUsage,
@@ -14,7 +14,7 @@ import type {
 
 @Injectable()
 export class SimManagementService {
-  constructor(private readonly simOrchestrator: SimOrchestratorService) {}
+  constructor(private readonly simOrchestrator: SimOrchestrator) {}
 
   /**
    * Debug method to check subscription data for SIM services

apps/bff/src/modules/subscriptions/sim-management/index.ts

@@ -1,5 +1,5 @@
 // Services
-export { SimOrchestratorService } from "./services/sim-orchestrator.service.js";
+export { SimOrchestrator } from "./services/sim-orchestrator.service.js";
 export { SimDetailsService } from "./services/sim-details.service.js";
 export { SimUsageService } from "./services/sim-usage.service.js";
 export { SimTopUpService } from "./services/sim-topup.service.js";

apps/bff/src/modules/subscriptions/sim-management/queue/sim-management.processor.ts

@@ -3,7 +3,7 @@ import { Inject, Injectable } from "@nestjs/common";
 import type { Job } from "bullmq";
 import { Logger } from "nestjs-pino";
 import { QUEUE_NAMES } from "@bff/infra/queue/queue.constants.js";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import {
   SIM_MANAGEMENT_JOB_NAMES as JOB_NAMES,
@@ -14,7 +14,7 @@ import {
 @Injectable()
 export class SimManagementProcessor extends WorkerHost {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     @Inject(Logger) private readonly logger: Logger
   ) {
     super();

apps/bff/src/modules/subscriptions/sim-management/services/esim-management.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, Inject, BadRequestException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ConfigService } from "@nestjs/config";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { SimValidationService } from "./sim-validation.service.js";
@@ -12,7 +12,7 @@ import type { SimReissueRequest, SimReissueFullRequest } from "@customer-portal/
 @Injectable()
 export class EsimManagementService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly whmcsClientService: WhmcsClientService,
     private readonly mappingsService: MappingsService,
     private readonly simValidation: SimValidationService,

apps/bff/src/modules/subscriptions/sim-management/services/sim-cancellation.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, Inject, BadRequestException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ConfigService } from "@nestjs/config";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { SalesforceOpportunityService } from "@bff/integrations/salesforce/services/salesforce-opportunity.service.js";
@@ -27,7 +27,7 @@ import { NOTIFICATION_SOURCE, NOTIFICATION_TYPE } from "@customer-portal/domain/
 @Injectable()
 export class SimCancellationService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly whmcsClientService: WhmcsClientService,
     private readonly mappingsService: MappingsService,
     private readonly opportunityService: SalesforceOpportunityService,

apps/bff/src/modules/subscriptions/sim-management/services/sim-details.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { SimValidationService } from "./sim-validation.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import type { SimDetails } from "@customer-portal/domain/sim";
@@ -8,7 +8,7 @@ import type { SimDetails } from "@customer-portal/domain/sim";
 @Injectable()
 export class SimDetailsService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly simValidation: SimValidationService,
     @Inject(Logger) private readonly logger: Logger
   ) {}

apps/bff/src/modules/subscriptions/sim-management/services/sim-orchestrator.service.ts

@@ -22,8 +22,13 @@ import type {
   SimReissueRequest,
 } from "@customer-portal/domain/sim";
 
+/**
+ * SIM Orchestrator
+ *
+ * Coordinates all SIM management operations by delegating to specialized services.
+ */
 @Injectable()
-export class SimOrchestratorService {
+export class SimOrchestrator {
   constructor(
     private readonly simDetails: SimDetailsService,
     private readonly simUsage: SimUsageService,

apps/bff/src/modules/subscriptions/sim-management/services/sim-plan.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, Inject, BadRequestException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ConfigService } from "@nestjs/config";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { SimValidationService } from "./sim-validation.service.js";
 import type {
   SimPlanChangeRequest,
@@ -35,7 +35,7 @@ const FREEBIT_PLAN_CODE_TO_SKU: Record<string, string> = Object.fromEntries(
 @Injectable()
 export class SimPlanService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly simValidation: SimValidationService,
     private readonly simSchedule: SimScheduleService,
     private readonly simQueue: SimManagementQueueService,

apps/bff/src/modules/subscriptions/sim-management/services/sim-topup.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, Inject, BadRequestException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
 import { ConfigService } from "@nestjs/config";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { SimValidationService } from "./sim-validation.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
@@ -13,7 +13,7 @@ import { SimTopUpPricingService } from "./sim-topup-pricing.service.js";
 @Injectable()
 export class SimTopUpService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly mappingsService: MappingsService,
     private readonly simValidation: SimValidationService,
     private readonly simBilling: SimBillingService,

apps/bff/src/modules/subscriptions/sim-management/services/sim-usage.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { SimValidationService } from "./sim-validation.service.js";
 import { SimUsageStoreService } from "../../sim-usage-store.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
@@ -14,7 +14,7 @@ import { SimScheduleService } from "./sim-schedule.service.js";
 @Injectable()
 export class SimUsageService {
   constructor(
-    private readonly freebitService: FreebitOperationsService,
+    private readonly freebitService: FreebitFacade,
     private readonly simValidation: SimValidationService,
     private readonly usageStore: SimUsageStoreService,
     private readonly simSchedule: SimScheduleService,

apps/bff/src/modules/subscriptions/sim-management/sim-management.module.ts

@@ -11,7 +11,7 @@ import { SimManagementService } from "../sim-management.service.js";
 // SimController is registered in SubscriptionsModule to ensure route order
 
 // Import all SIM management services
-import { SimOrchestratorService } from "./services/sim-orchestrator.service.js";
+import { SimOrchestrator } from "./services/sim-orchestrator.service.js";
 import { SimDetailsService } from "./services/sim-details.service.js";
 import { SimUsageService } from "./services/sim-usage.service.js";
 import { SimTopUpService } from "./services/sim-topup.service.js";
@@ -65,7 +65,7 @@ import { WorkflowModule } from "@bff/modules/shared/workflow/index.js";
     SimPlanService,
     SimCancellationService,
     EsimManagementService,
-    SimOrchestratorService,
+    SimOrchestrator,
     SimBillingService,
     SimScheduleService,
     SimManagementQueueService,
@@ -81,7 +81,7 @@ import { WorkflowModule } from "@bff/modules/shared/workflow/index.js";
     },
   ],
   exports: [
-    SimOrchestratorService,
+    SimOrchestrator,
     // Export individual services in case they're needed elsewhere
     SimDetailsService,
     SimUsageService,

apps/bff/src/modules/subscriptions/sim-order-activation.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, BadRequestException, Inject, ConflictException } from "@nestjs/common";
 import { Logger } from "nestjs-pino";
-import { FreebitOperationsService } from "@bff/integrations/freebit/services/freebit-operations.service.js";
+import { FreebitFacade } from "@bff/integrations/freebit/facades/freebit.facade.js";
 import { WhmcsOrderService } from "@bff/integrations/whmcs/services/whmcs-order.service.js";
 import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { CacheService } from "@bff/infra/cache/cache.service.js";
@@ -13,7 +13,7 @@ import { SimScheduleService } from "./sim-management/services/sim-schedule.servi
 @Injectable()
 export class SimOrderActivationService {
   constructor(
-    private readonly freebit: FreebitOperationsService,
+    private readonly freebit: FreebitFacade,
     private readonly whmcsOrderService: WhmcsOrderService,
     private readonly mappings: MappingsService,
     private readonly cache: CacheService,

apps/bff/src/modules/subscriptions/subscriptions.service.ts

@@ -11,7 +11,7 @@ import type {
 } from "@customer-portal/domain/subscriptions";
 import type { Invoice, InvoiceItem, InvoiceList } from "@customer-portal/domain/billing";
 import { WhmcsCacheService } from "@bff/integrations/whmcs/cache/whmcs-cache.service.js";
-import { WhmcsConnectionOrchestratorService } from "@bff/integrations/whmcs/connection/services/whmcs-connection-orchestrator.service.js";
+import { WhmcsConnectionFacade } from "@bff/integrations/whmcs/facades/whmcs.facade.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
 import { WhmcsInvoiceService } from "@bff/integrations/whmcs/services/whmcs-invoice.service.js";
 import { WhmcsSubscriptionService } from "@bff/integrations/whmcs/services/whmcs-subscription.service.js";
@@ -30,7 +30,7 @@ export class SubscriptionsService {
     private readonly whmcsSubscriptionService: WhmcsSubscriptionService,
     private readonly whmcsInvoiceService: WhmcsInvoiceService,
     private readonly whmcsClientService: WhmcsClientService,
-    private readonly whmcsConnectionService: WhmcsConnectionOrchestratorService,
+    private readonly whmcsConnectionService: WhmcsConnectionFacade,
     private readonly cacheService: WhmcsCacheService,
     private readonly mappingsService: MappingsService,
     @Inject(Logger) private readonly logger: Logger

apps/bff/src/modules/users/application/users.facade.ts

@@ -6,7 +6,7 @@ import type { BilingualAddress } from "@customer-portal/domain/address";
 import type { DashboardSummary } from "@customer-portal/domain/dashboard";
 import type { UpdateCustomerProfileRequest } from "@customer-portal/domain/auth";
 import { UserAuthRepository } from "../infra/user-auth.repository.js";
-import { UserProfileService } from "../infra/user-profile.service.js";
+import { UserProfileAggregator } from "../infra/user-profile.service.js";
 import { extractErrorMessage } from "@bff/core/utils/error.util.js";
 import { mapPrismaUserToDomain } from "@bff/infra/mappers/index.js";
 
@@ -18,7 +18,7 @@ type AuthUpdateData = Partial<
 export class UsersFacade {
   constructor(
     private readonly authRepository: UserAuthRepository,
-    private readonly profileService: UserProfileService,
+    private readonly profileService: UserProfileAggregator,
     @Inject(Logger) private readonly logger: Logger
   ) {}
 

apps/bff/src/modules/users/infra/user-profile.service.ts

@@ -36,20 +36,27 @@ import { MappingsService } from "@bff/modules/id-mappings/mappings.service.js";
 import { WhmcsClientService } from "@bff/integrations/whmcs/services/whmcs-client.service.js";
 import { WhmcsInvoiceService } from "@bff/integrations/whmcs/services/whmcs-invoice.service.js";
 import { WhmcsSubscriptionService } from "@bff/integrations/whmcs/services/whmcs-subscription.service.js";
-import { SalesforceService } from "@bff/integrations/salesforce/salesforce.service.js";
+import { SalesforceFacade } from "@bff/integrations/salesforce/facades/salesforce.facade.js";
 import { withErrorHandling } from "@bff/core/utils/error-handler.util.js";
 import { parseUuidOrThrow } from "@bff/core/utils/validation.util.js";
 import { UserAuthRepository } from "./user-auth.repository.js";
 
+/**
+ * User Profile Aggregator
+ *
+ * Combines user data from multiple sources (Portal DB, WHMCS, Salesforce)
+ * to build comprehensive user profiles. Handles profile reads and
+ * coordinated updates across systems.
+ */
 @Injectable()
-export class UserProfileService {
+export class UserProfileAggregator {
   constructor(
     private readonly userAuthRepository: UserAuthRepository,
     private readonly mappingsService: MappingsService,
     private readonly whmcsClientService: WhmcsClientService,
     private readonly whmcsInvoiceService: WhmcsInvoiceService,
     private readonly whmcsSubscriptionService: WhmcsSubscriptionService,
-    private readonly salesforceService: SalesforceService,
+    private readonly salesforceService: SalesforceFacade,
     private readonly configService: ConfigService,
     @Inject(Logger) private readonly logger: Logger
   ) {}

apps/bff/src/modules/users/users.module.ts

@@ -1,7 +1,7 @@
 import { Module } from "@nestjs/common";
 import { UsersFacade } from "./application/users.facade.js";
 import { UserAuthRepository } from "./infra/user-auth.repository.js";
-import { UserProfileService } from "./infra/user-profile.service.js";
+import { UserProfileAggregator } from "./infra/user-profile.service.js";
 import { UsersController } from "./users.controller.js";
 import { WhmcsModule } from "@bff/integrations/whmcs/whmcs.module.js";
 import { SalesforceModule } from "@bff/integrations/salesforce/salesforce.module.js";
@@ -11,7 +11,7 @@ import { PrismaModule } from "@bff/infra/database/prisma.module.js";
 @Module({
   imports: [PrismaModule, WhmcsModule, SalesforceModule, MappingsModule],
   controllers: [UsersController],
-  providers: [UsersFacade, UserAuthRepository, UserProfileService],
+  providers: [UsersFacade, UserAuthRepository, UserProfileAggregator],
-  exports: [UsersFacade, UserAuthRepository, UserProfileService],
+  exports: [UsersFacade, UserAuthRepository, UserProfileAggregator],
 })
 export class UsersModule {}