1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// Managing cross-cutting concerns across BFFs
 
// ❌ ANTIPATTERN: Copy-pasting across BFFs
// Mobile BFF
class MobileLogging {
  log(level: string, message: string, context: object) {
    console.log(JSON.stringify({ level, message, ...context, bff: 'mobile' }));
  }
}
 
// Web BFF - slight variation leads to divergence
class WebLogging {
  log(level: string, msg: string, ctx: Record<string, any>) {
    console.log(JSON.stringify({ level, msg, context: ctx, source: 'web-bff' }));
  }
}
// These will drift further over time...
 
// ✅ CORRECT: Shared library with BFF-specific configuration
// Shared package: @company/bff-core
export interface BFFLoggingConfig {
  bffName: string;
  environment: string;
  samplingRate: number;
}
 
export class BFFLogger {
  constructor(private config: BFFLoggingConfig) {}
  
  log(level: LogLevel, message: string, context: LogContext) {
    const entry: LogEntry = {
      timestamp: Date.now(),
      level,
      message,
      bff: this.config.bffName,
      environment: this.config.environment,
      traceId: context.traceId,
      spanId: context.spanId,
      ...context.custom,
    };
    
    if (Math.random() < this.config.samplingRate) {
      this.emit(entry);
    }
  }
}
 
// Each BFF imports and configures
// mobile-bff/src/logging.ts
import { BFFLogger } from '@company/bff-core';
export const logger = new BFFLogger({
  bffName: 'mobile',
  environment: process.env.NODE_ENV,
  samplingRate: 0.1,
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

// Observability requirements for BFF environments
 
interface BFFObservabilityRequirements {
  // Per-BFF metrics
  metrics: {
    requestsPerSecond: Gauge;
    latencyHistogram: Histogram;    // p50, p95, p99
    errorRate: Counter;
    downstreamLatency: Histogram;   // Per downstream service
    cacheHitRate: Gauge;
    coalescingEfficiency: Gauge;
  };
  
  // Per-BFF dashboards
  dashboards: {
    overview: 'request rate, error rate, latency';
    downstream: 'per-service latency and error rates';
    cache: 'hit rates, eviction rates, memory usage';
    alerts: 'active alerts, recent incidents';
  };
  
  // Cross-BFF aggregation views
  aggregatedViews: {
    downstreamLoad: 'total load on each downstream service from all BFFs';
    errorCorrelation: 'are errors correlated across BFFs (backend issue)?';
    trafficDistribution: 'percentage of traffic per BFF over time';
    comparePerformance: 'same endpoint performance across BFFs';
  };
  
  // Distributed tracing requirements
  tracing: {
    propagation: 'W3C Trace Context across all BFFs';
    sampling: 'consistent sampling rate for cross-BFF traces';
    retention: 'enough history to debug production issues';
    correlation: 'link client session to BFF request to downstream calls';
  };
}
 
// Alert configuration multiplies
const alertConfigs = {
  mobileBFF: {
    highErrorRate: { threshold: 0.01, window: '5m' },
    highLatency: { p99Threshold: 500, window: '5m' },
    downstreamCircuitOpen: { services: ['user', 'content', 'recommendations'] },
  },
  webBFF: {
    highErrorRate: { threshold: 0.005, window: '5m' },  // Different threshold
    highLatency: { p99Threshold: 300, window: '5m' },   // Stricter latency
    downstreamCircuitOpen: { services: ['user', 'content', 'recommendations', 'analytics'] },
  },
  tvBFF: {
    highErrorRate: { threshold: 0.02, window: '10m' },  // More lenient
    highLatency: { p99Threshold: 1000, window: '10m' }, // Higher latency acceptable
    downstreamCircuitOpen: { services: ['content', 'recommendations'] },
  },
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

// Practical duplication strategy
 
// SHARED: @company/bff-core
// - Service client stubs (auto-generated from OpenAPI/gRPC)
// - Authentication middleware
// - Circuit breaker wrapper
// - Logging infrastructure
// - Metrics client
 
// SHARED: @company/bff-common
// - Domain types (User, Product, etc.) if stable
// - Common utilities (date formatting, currency, etc.)
// ⚠️ Be very selective here - this package tends to grow unwieldy
 
// DUPLICATED: Each BFF
// - API routes and handlers
// - Response transformation
// - Aggregation orchestration
// - Client-specific error formatting
// - Feature flags interpretation
 
// Example of correct duplication
// web-bff/src/handlers/product.ts
export async function getProduct(req: Request): Promise<WebProductResponse> {
  const product = await productService.get(req.params.id);
  
  // Web-specific transformation - SHOULD be duplicated
  return {
    id: product.id,
    name: product.name,
    description: product.fullDescription,  // Web gets full description
    images: product.images.map(i => ({
      ...i,
      srcset: generateSrcSet(i),  // Web uses srcset
    })),
    seo: {                                  // Web-only SEO data
      title: product.seoTitle,
      description: product.seoDescription,
      structuredData: generateProductSchema(product),
    },
  };
}
 
// mobile-bff/src/handlers/product.ts
export async function getProduct(req: Request): Promise<MobileProductResponse> {
  const product = await productService.get(req.params.id);
  
  // Mobile-specific transformation - SHOULD be duplicated
  return {
    id: product.id,
    name: product.name,
    description: truncate(product.fullDescription, 200),  // Shorter
    thumbnail: product.images[0]?.url,  // Just one image URL
    // No SEO data - mobile doesn't need it
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// Contract testing requirements for BFF architecture
 
// Each BFF maintains consumer contracts (Pact or similar)
// mobile-bff/contracts/product-service.pact.ts
import { Pact } from '@pact-foundation/pact';
 
describe('Mobile BFF → Product Service Contract', () => {
  const provider = new Pact({
    consumer: 'mobile-bff',
    provider: 'product-service',
    port: 1234,
  });
 
  describe('GET /products/:id', () => {
    it('returns product details', async () => {
      await provider.addInteraction({
        state: 'product 123 exists',
        uponReceiving: 'a request for product 123',
        withRequest: {
          method: 'GET',
          path: '/products/123',
          headers: {
            'Accept': 'application/json',
          },
        },
        willRespondWith: {
          status: 200,
          headers: {
            'Content-Type': 'application/json',
          },
          body: {
            id: like('123'),
            name: like('Sample Product'),
            fullDescription: like('A sample product description'),
            images: eachLike({
              url: like('https://cdn.example.com/image.jpg'),
              width: like(800),
              height: like(600),
            }),
          },
        },
      });
 
      // Execute the contract test
      const response = await mobileBFFClient.getProduct('123');
      expect(response.id).toBe('123');
      
      await provider.verify();
    });
  });
});
 
// Provider side: product-service verifies contracts from all BFFs
// product-service/test/pact-verification.ts
describe('Product Service Provider Verification', () => {
  it('satisfies mobile-bff contract', async () => {
    await verifier.verifyProvider({
      provider: 'product-service',
      pactBrokerUrl: process.env.PACT_BROKER_URL,
      consumerVersionSelectors: [
        { consumer: 'mobile-bff', mainBranch: true },
        { consumer: 'web-bff', mainBranch: true },
        { consumer: 'tv-bff', mainBranch: true },
      ],
      publishVerificationResult: true,
    });
  });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// ❌ ANTIPATTERN: Shared BFF serving multiple clients
 
app.get('/api/products/:id', async (req, res) => {
  const product = await productService.get(req.params.id);
  
  // Trying to serve everyone with conditional logic
  const clientType = req.headers['x-client-type'];
  
  if (clientType === 'mobile') {
    res.json({
      id: product.id,
      name: product.name,
      thumbnail: product.images[0].url,
    });
  } else if (clientType === 'web') {
    res.json({
      id: product.id,
      name: product.name,
      description: product.fullDescription,
      images: product.images.map(i => ({ ...i, srcset: generateSrcSet(i) })),
      seo: generateSEO(product),
    });
  } else if (clientType === 'tv') {
    res.json({
      id: product.id,
      title: product.name,
      hero: product.images.find(i => i.type === 'hero')?.url,
    });
  } else {
    // Default? All? Error?
    res.json(product);
  }
});
 
// This defeats the BFF purpose:
// - Changes for one client risk breaking others
// - Single point of contention
// - All the complexity of BFF, none of the benefits

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

// ❌ ANTIPATTERN: Business logic leaking into BFF
 
app.post('/api/orders', async (req, res) => {
  const { userId, productId, quantity } = req.body;
  
  // ❌ BFF is now making business decisions
  const product = await productService.get(productId);
  const inventory = await inventoryService.get(productId);
  
  // Business rule: check if user can order
  if (quantity > inventory.available) {
    return res.status(400).json({ error: 'Insufficient inventory' });
  }
  
  // Business rule: apply pricing
  const user = await userService.get(userId);
  const price = user.membershipLevel === 'premium' 
    ? product.price * 0.9  // ❌ Discount logic in BFF!
    : product.price;
  
  // Business rule: calculate shipping
  const shipping = quantity > 3 ? 0 : 5.99;  // ❌ Shipping rules in BFF!
  
  // If this logic exists in mobile BFF, must it be copied to web BFF?
  // Now you have divergent business rules across BFFs.
  
  const order = await orderService.create({
    userId, productId, quantity, price, shipping
  });
  
  res.json(order);
});
 
// ✅ CORRECT: BFF orchestrates, domain service decides
app.post('/api/orders', async (req, res) => {
  const { userId, productId, quantity } = req.body;
  
  // BFF validates input format, not business rules
  if (!productId || quantity < 1) {
    return res.status(400).json({ 
      error: 'Invalid input',
      fields: { productId: 'required', quantity: 'must be >= 1' }
    });
  }
  
  // Domain service handles all business logic
  const order = await orderService.create({ userId, productId, quantity });
  
  // BFF only transforms response for client
  res.json(transformOrderForMobile(order));
});