Assist_Design/docs/bff/BFF-INTEGRATION-PATTERNS-GUIDE.md

BFF Integration Layer Patterns

Overview

The BFF Integration Layer is responsible for communicating with external systems (Salesforce, WHMCS, Freebit, etc.) and transforming their responses into domain types. This document describes the clean architecture patterns we follow.

Core Principle: "Map Once, Use Everywhere"

Domain mappers are the ONLY place that transforms raw provider data to domain types.

Everything else just uses the domain types directly.

┌──────────────┐    ┌───────────────────┐    ┌──────────────┐    ┌────────────┐
│ External API │ →  │ Integration       │ →  │ Domain       │ →  │ Use        │
│ (Raw Data)   │    │ Service           │    │ Mapper       │    │ Everywhere │
└──────────────┘    └───────────────────┘    └──────────────┘    └────────────┘
                                               ↑
                                               SINGLE transformation
                                               in domain layer!

Integration Service Pattern

Structure

Each integration service follows this pattern:

apps/bff/src/integrations/{provider}/
├── services/
│   ├── {provider}-connection.service.ts   # HTTP client, auth
│   ├── {provider}-{entity}.service.ts     # Entity-specific operations
│   └── {provider}-orchestrator.service.ts # Coordinates multiple operations
├── utils/
│   └── {entity}-query-builder.ts          # Query construction (SOQL, etc.)
└── {provider}.module.ts

Integration Service Responsibilities

1. ✅ Build queries (SOQL, API parameters)
2. ✅ Execute API calls (HTTP, authentication)
3. ✅ Use domain mappers to transform responses
4. ✅ Return domain types
5. ❌ NO additional mapping beyond domain mappers
6. ❌ NO business logic

Example: SalesforceOrderService

import { Injectable } from "@nestjs/common";
import { SalesforceConnection } from "./salesforce-connection.service";
import { buildOrderSelectFields } from "../utils/order-query-builder";
import {
  Providers as OrderProviders,
  type OrderDetails,
  type SalesforceOrderRecord,
} from "@customer-portal/domain/orders";

@Injectable()
export class SalesforceOrderService {
  constructor(private readonly sf: SalesforceConnection) {}

  async getOrderById(orderId: string): Promise<OrderDetails | null> {
    // 1. Build query (infrastructure concern)
    const fields = buildOrderSelectFields(["Account.Name"]).join(", ");
    const soql = `
      SELECT ${fields}
      FROM Order
      WHERE Id = '${orderId}'
      LIMIT 1
    `;

    // 2. Execute query
    const result = await this.sf.query(soql);
    const order = result.records?.[0];
    
    if (!order) return null;

    // 3. Use domain mapper (SINGLE transformation!)
    return OrderProviders.Salesforce.transformSalesforceOrderDetails(order, []);
  }
}

✅ Correct Pattern: Direct Domain Mapper Usage

// In integration service
const defaultCurrency = this.currencyService.getDefaultCurrency();
const invoice = Providers.Whmcs.transformWhmcsInvoice(rawInvoice, {
  defaultCurrencyCode: defaultCurrency.code,
  defaultCurrencySymbol: defaultCurrency.prefix || defaultCurrency.suffix,
});

❌ Anti-Pattern: Wrapper Services

// DON'T DO THIS - Redundant wrapper!
@Injectable()
export class InvoiceTransformerService {
  transformInvoice(whmcsInvoice: WhmcsInvoice): Invoice {
    return Providers.Whmcs.transformWhmcsInvoice(whmcsInvoice, {...});
  }
}

// This just adds an extra layer with no value!

Query Builders

Query builders belong in the BFF integration layer because they are infrastructure concerns.

Location

apps/bff/src/integrations/{provider}/utils/
├── order-query-builder.ts
├── catalog-query-builder.ts
└── soql.util.ts

Example: Order Query Builder

import { UNIQUE } from "./soql.util";

/**
 * Build SOQL SELECT fields for Order queries
 */
export function buildOrderSelectFields(additional: string[] = []): string[] {
  const fields = [
    "Id", "AccountId", "Status", "Type", "EffectiveDate", 
    "OrderNumber", "TotalAmount", "CreatedDate"
  ];
  return UNIQUE([...fields, ...additional]);
}

/**
 * Build SOQL SELECT fields for OrderItem queries
 */
export function buildOrderItemSelectFields(additional: string[] = []): string[] {
  const fields = [
    "Id", "OrderId", "Quantity", "UnitPrice", "TotalPrice"
  ];
  return UNIQUE([...fields, ...additional]);
}

Common Integration Patterns

Pattern 1: Simple Fetch and Transform

async getEntity(id: string): Promise<DomainType | null> {
  // 1. Build query
  const soql = buildQuery(id);
  
  // 2. Execute
  const result = await this.connection.query(soql);
  
  if (!result.records?.[0]) return null;
  
  // 3. Transform with domain mapper
  return Providers.{Provider}.transform{Entity}(result.records[0]);
}

Pattern 2: Fetch with Related Data

async getOrderWithItems(orderId: string): Promise<OrderDetails | null> {
  // 1. Build queries for both order and items
  const orderSoql = buildOrderQuery(orderId);
  const itemsSoql = buildOrderItemsQuery(orderId);
  
  // 2. Execute in parallel
  const [orderResult, itemsResult] = await Promise.all([
    this.sf.query(orderSoql),
    this.sf.query(itemsSoql),
  ]);
  
  const order = orderResult.records?.[0];
  if (!order) return null;
  
  const items = itemsResult.records ?? [];
  
  // 3. Transform with domain mapper (handles both order and items)
  return OrderProviders.Salesforce.transformSalesforceOrderDetails(order, items);
}

Pattern 3: Batch Transform with Error Handling

async getInvoices(clientId: number): Promise<Invoice[]> {
  // 1. Fetch from API
  const response = await this.whmcsClient.getInvoices({ clientId });
  
  if (!response.invoices?.invoice) return [];
  
  // 2. Get infrastructure context (currency)
  const defaultCurrency = this.currencyService.getDefaultCurrency();
  
  // 3. Transform batch with error handling
  const invoices: Invoice[] = [];
  for (const whmcsInvoice of response.invoices.invoice) {
    try {
      const transformed = Providers.Whmcs.transformWhmcsInvoice(whmcsInvoice, {
        defaultCurrencyCode: defaultCurrency.code,
        defaultCurrencySymbol: defaultCurrency.prefix || defaultCurrency.suffix,
      });
      invoices.push(transformed);
    } catch (error) {
      this.logger.error(`Failed to transform invoice ${whmcsInvoice.id}`, { error });
    }
  }
  
  return invoices;
}

Pattern 4: Create/Update Operations

async createOrder(orderFields: Record<string, unknown>): Promise<{ id: string }> {
  this.logger.log({ orderType: orderFields.Type }, "Creating Salesforce Order");
  
  try {
    const created = await this.sf.sobject("Order").create(orderFields);
    this.logger.log({ orderId: created.id }, "Salesforce Order created successfully");
    return created;
  } catch (error) {
    this.logger.error("Failed to create Salesforce Order", { error });
    throw error;
  }
}

Integration with Caching

async getInvoice(invoiceId: number, userId: string): Promise<Invoice> {
  // 1. Check cache
  const cached = await this.cacheService.getInvoice(userId, invoiceId);
  if (cached) return cached;
  
  // 2. Fetch from API
  const response = await this.whmcsClient.getInvoice({ invoiceid: invoiceId });
  
  // 3. Transform with domain mapper
  const defaultCurrency = this.currencyService.getDefaultCurrency();
  const invoice = Providers.Whmcs.transformWhmcsInvoice(response, {
    defaultCurrencyCode: defaultCurrency.code,
    defaultCurrencySymbol: defaultCurrency.prefix || defaultCurrency.suffix,
  });
  
  // 4. Cache and return
  await this.cacheService.setInvoice(userId, invoiceId, invoice);
  return invoice;
}

Context Injection Pattern

Some transformations need infrastructure context (like currency). Pass it explicitly:

// ✅ Correct: Inject infrastructure context
const defaultCurrency = this.currencyService.getDefaultCurrency();
const subscription = Providers.Whmcs.transformWhmcsSubscription(whmcsProduct, {
  defaultCurrencyCode: defaultCurrency.code,
  defaultCurrencySymbol: defaultCurrency.prefix || defaultCurrency.suffix,
});

Why this is clean:

• Domain mapper is pure (deterministic for same inputs)
• Infrastructure concern (currency) is injected from BFF
• No service wrapper needed

Module Organization

@Module({
  imports: [ConfigModule],
  providers: [
    // Connection services
    SalesforceConnection,
    
    // Entity-specific integration services
    SalesforceOrderService,
    SalesforceAccountService,
    
    // Main service
    SalesforceService,
  ],
  exports: [
    SalesforceService,
    SalesforceOrderService, // Export for use in other modules
  ],
})
export class SalesforceModule {}

Anti-Patterns to Avoid

❌ Transformer Services

// DON'T: Create wrapper services that just call domain mappers
@Injectable()
export class InvoiceTransformerService {
  transformInvoice(raw: WhmcsInvoice): Invoice {
    return Providers.Whmcs.transformWhmcsInvoice(raw, {...});
  }
}

Why it's bad:

• Adds unnecessary layer
• No value beyond what domain mapper provides
• Makes codebase harder to understand

Instead: Use domain mapper directly in integration service

❌ Mapper Services

// DON'T: Wrap domain mappers in injectable services
@Injectable()
export class FreebitMapperService {
  mapToSimDetails(response: unknown): SimDetails {
    return FreebitProvider.transformFreebitAccountDetails(response);
  }
}

Why it's bad:

• Just wraps domain mapper
• Adds injection complexity for no benefit

Instead: Import domain mapper directly and use it

❌ Multiple Transformations

// DON'T: Transform multiple times
const rawData = await api.fetch();
const intermediate = this.customTransform(rawData);
const domainType = Providers.X.transform(intermediate);

Why it's bad:

• Multiple transformation points
• Risk of data inconsistency
• Harder to maintain

Instead: Transform once using domain mapper

Best Practices

✅ DO

1. Keep integration services thin - just fetch and transform
2. Use domain mappers directly - no wrappers
3. Build queries in utils - separate query construction
4. Handle errors gracefully - log and throw/return null
5. Cache when appropriate - reduce API calls
6. Inject context explicitly - currency, config, etc.
7. Return domain types - never return raw API responses

❌ DON'T

1. Create wrapper services - use domain mappers directly
2. Add business logic - belongs in domain or orchestrators
3. Transform twice - map once in domain
4. Expose raw types - always return domain types
5. Hard-code queries - use query builders
6. Skip error handling - always log failures

Summary

Integration services are responsible for:

• 🔧 Building queries (SOQL, API params)
• 🌐 Executing API calls
• 🔄 Using domain mappers to transform responses
• 📦 Returning domain types

Integration services should NOT:

• ❌ Wrap domain mappers in services
• ❌ Add additional transformation layers
• ❌ Contain business logic
• ❌ Expose raw provider types

Remember: "Map Once, Use Everywhere" - domain mappers are the single source of truth for transformations.