This document describes the Backend-for-Frontend (BFF) microservices architecture for the Flight Booking. The BFF exposes secure APIs to the React TypeScript frontend and integrates with:

• Token-based authentication
• Third-party Flight Search APIs
• Redis Cache (5-minute TTL)
• Booking Service (MySQL)
• Payment Gateway

• Pino
• Pino-Http
• OpenTelemetry
• Cloud Logging (ELK / CloudWatch / Loki)

[Frontend] → login → [Auth Service] \
           ← JWT Token \
[Frontend] → API calls with Bearer Token → [BFF]

Tokens are validated per request.

• Supplier API calls are expensive and time-sensitive
• Data is cached in Redis for 300 seconds
• UI retrieves additional details from cache (“Show More”)

flights:{origin}:{destination}:{date}:{userID}:{searchHash}

Examples:

flights:BOM:DXB:2025-03-21:user123:8f3c0e1a76

Search Flights → Cache Results
Select Flight → Create booking
Initiate Payment → Payment Gateway
Webhook Received → Confirm booking
Persist in MySQL → Send Confirmation

src/
 ├ api/
 │   ├ controllers/
 │   ├ routes/
 │   ├ middlewares/
 │   └ errors/
 ├ domain/
 │   ├ entities/
 │   ├ services/
 │   ├ repositories/
 │   └ errors/
 ├ infrastructure/
 │   ├ db/
 │   ├ redis/
 │   ├ logger/
 │   ├ http/
 │   └ errors/
 └ tests/

ts

import mysql from 'mysql2/promise';

export const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  database: process.env.DB_NAME,
  password: process.env.DB_PASS,
  connectionLimit: 10,
});

json

{
  "searchId": "abc123",
  "key": "flights:BOM:DXB:2025-03-21:hash",
  "flights": [
    {
      "flightNo": "EK501",
      "origin": "BOM",
      "destination": "DXB",
      "duration": "3h 10m",
      "price": 450,
      "currency": "USD",
      "airline": "Emirates"
    }
  ]
}

ts

const FLIGHT_TTL_SECONDS = 300;

await redis.set(key, JSON.stringify(dto), {
  EX: FLIGHT_TTL_SECONDS,
  NX: true
});

On Expiry → user resubmits search.

Documented endpoints:

• /api/flights/search
• /api/flights/details

openapi.yaml

openapi: 3.0.3
info:
  title: Flight Search API
  version: 1.0.0
  description: Backend-for-frontend service for searching & retrieving cached flight results.

servers:
  - url: /api

paths:
  /flights/search:
    post:
      summary: Search flights (cached for 5 minutes)
      tags:
        - Flights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightSearchRequest'
      responses:
        '200':
          description: Search results DTO
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightSearchResponse'
        '500':
          description: Internal server error

  /flights/details:
    get:
      summary: Retrieve flight details from Redis cache
      tags:
        - Flights
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
          description: Redis cache key returned by search API
      responses:
        '200':
          description: Cached flight result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightSearchResponse'
        '404':
          description: Cache expired or key not found
        '500':
          description: Internal server error

components:
  schemas:
    FlightSearchRequest:
      type: object
      required:
        - origin
        - destination
        - date
      properties:
        origin:
          type: string
          example: BOM
        destination:
          type: string
          example: DXB
        date:
          type: string
          format: date
          example: 2025-03-21
        pax:
          type: integer
          example: 1
        cabinClass:
          type: string
          example: ECONOMY

    FlightSearchResponse:
      type: object
      properties:
        searchId:
          type: string
          example: abc123
        key:
          type: string
          example: flights:BOM:DXB:2025-03-21:8f3c0e1a76
        flights:
          type: array
          items:
            $ref: '#/components/schemas/FlightItem'

    FlightItem:
      type: object
      properties:
        flightNo:
          type: string
          example: EK501
        origin:
          type: string
          example: BOM
        destination:
          type: string
          example: DXB
        duration:
          type: string
          example: 3h 10m
        price:
          type: number
          example: 450
        currency:
          type: string
          example: USD
        airline:
          type: string
          example: Emirates

Swagger UI:

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc));

Swagger UI Setup (Express) ts

import swaggerUi from 'swagger-ui-express'; \
import yaml from 'yamljs';

const swaggerDoc = yaml.load('./openapi.yaml'); \
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc));

Docs available at: bash

/docs

Covers:

• Cache hit
• Cache miss
• TTL set

• Trace every request end-to-end
• JSON structured logs
• Query by:
  • user
  • booking
  • redis key
  • trace id
• Support dashboards & SLIs

Every inbound HTTP request receives:

These flow through:

Frontend → BFF → Redis → MySQL → Payment → Logs

bash

timestamp
service
env
requestId
traceId
spanId
userId
BookingId
redisKey
durationMs
status
message

bash

npm i pino pino-http pino-pretty

ts

import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  base: {
    service: 'bff-gateway',
    env: process.env.NODE_ENV
  },
  timestamp: pino.stdTimeFunctions.isoTime
});

ts

import pinoHttp from 'pino-http';
import { randomUUID } from 'crypto';
import { logger } from './logger';

export const httpLogger = pinoHttp({
  logger,
  genReqId: (req) =>
    req.headers['x-request-id']?.toString() || randomUUID(),
  customProps: (req) => ({
    userId: req.user?.id,
  })
});

ts

app.use(httpLogger);

app.use((req, res, next) => {
  req.log.info({ path: req.path }, 'request received');
  next();
});

ts

req.log.info({
  bkgId,
  redisKey,
  step: 'booking-confirmation'
}, 'Booking confirmed');

Should attach:

• traceId
• spanId

• distributed tracing
• flame graphs
• error attribution

Code to link trace → logs → DB query

Never log:

• passwords
• card numbers
• tokens
• PII

ts

describe('logger', () => {
  it('logs JSON structure', () => {
    const log = logger.info({ test: true }, 'hello');
    expect(log).toBeDefined();
  });
});

1. Client Errors (4xx)

2. Server Errors (5xx)

3. Business Errors

1. Business / Domain Errors

When business rule is violeted - /src/domain/errors ts

export class FlightUnavailableError extends Error {
  code = 'FLIGHT_UNAVAILABLE';
}

2. Application Errors

Use-case level
Validation / workflow / orchestration

/src/application/errors ts

export class ValidationError extends Error {
  status = 400;
  code = 'VALIDATION_ERROR';
}

3. Infrastructure Errors

ONLY for wrapping technical failures

/src/infrastructure/errors ts

export class RedisConnectionError extends Error {
  code = 'REDIS_CONNECTION_ERROR';
}

BUT — these should usually be mapped upward into application-level errors.

Example mapping: ts

try {
   await redis.get(key);
} catch(e) {
   throw new CacheUnavailableError();
}

So the API layer never leaks Redis internals.

Infrastructure error
   ⬇ wrap / map
Application error
   ⬇ serialized to client
HTTP response

final structure should look like

/src
 ┣ /domain
 ┃   ┗ /errors   ← Business rule errors
 ┣ /application
 ┃   ┗ /errors   ← Validation + workflow errors
 ┣ /infrastructure
 ┃   ┗ /errors   ← Technical adapter errors (wrapped)
 ┗ /api (interfaces)
     ┗ error-middleware.ts  ← converts to HTTP response

What to AVOID

Defining all errors in infrastructure
→ couples business logic to technology

Throwing raw DB/Redis errors upward
→ leaks internal details

Mixed styles (sometimes returning strings, sometimes errors)
→ debugging nightmare