wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Flight Booking BFF — Microservices Architecture & Implementation Guide ======

===== Overview =====

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

===== Architecture Summary =====

==== Key Services / Core Components ====

^Service^Responsibility^Local Port|
|**API Gateway / BFF (Node.js)** |Single entry point for UI|4000|
|**Auth Service** |Issues & validates tokens|4001|
|**Flight Service** |Calls supplier API + Redis cache|4002|
|**Booking Service (MySQL)** |Stores booking data|4003|
|**Payment Service** |Payment initiation + webhooks|4004|


==== Observability Stack ====

  * **Pino**
  * **Pino-Http**
  * **OpenTelemetry**
  * **Cloud Logging (ELK / CloudWatch / Loki)**
=== Token Flow Diagram ===
<code>

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

</code>

Tokens are validated per request.

==== Flight Caching Strategy (Redis — 5 mins TTL) ====

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

==== Redis Key Naming Convention ====

<code>
flights:{origin}:{destination}:{date}:{userID}:{searchHash}

</code>

Examples:

<code>
flights:BOM:DXB:2025-03-21:user123:8f3c0e1a76

</code>

===== Booking Workflow — Sequence =====

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

</code>

===== Node.js Folder Structure (Clean Architecture) =====

^Layer^Purpose^Examples^Should define errors?|
|**Domain** |Business rules|Entities, aggregates|**Business errors ** |
|**Domain/Application** |Use-cases / orchestration|Services, DTOs|**App errors ** |
|**Infrastructure** |Technical adapters|DB, Redis, HTTP|**Adapter-only errors ** |
|**Interface/API** |Controllers|REST/GraphQL|no core errors|
<code>

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

</code>




===== MySQL — Connection Pool =====
 <font 9px/inherit;;inherit;;inherit>ts</font>

<code>
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,
});

</code>

===== DTO Design Example =====
 <font 9px/inherit;;inherit;;inherit>json</font>

<code>
{
  "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"
    }
  ]
}

</code>

===== Redis Caching (5-Minute TTL) =====
 <font 9px/inherit;;inherit;;inherit>ts</font>

<code>
const FLIGHT_TTL_SECONDS = 300;

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

</code>

==== Expiry UX ====

On Expiry → user resubmits search.

===== Swagger / OpenAPI Spec =====

Documented endpoints:

  * ''/api/flights/search''
  * ''/api/flights/details''
openapi.yaml

<code>
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

</code>

Swagger UI:

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

</code>

Swagger UI Setup (Express)
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

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

</code>

Docs available at:
 <font 9px/inherit;;inherit;;inherit>bash</font>

<code>
/docs

</code>

====== Jest Unit Tests ======

===== Cache Hit / Miss =====

Covers:

  * Cache hit
  * Cache miss
  * TTL set

====== Centralized Logging & Observability Strategy ======

==== Goals ====

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

===== Correlation ID Strategy =====

Every inbound HTTP request receives:

^Field^Purpose|
|''requestId'' |Per-request UUID|
|''traceId'' |OpenTelemetry Trace|
|''spanId'' |Span identifier|
|''userId'' |user id|
|''bookingId'' |booking id|
|''redisKey'' |Record Key|

These flow through:

Frontend → BFF → Redis → MySQL → Payment → Logs

===== Redis + MySQL Log Correlation =====

^Attribute^Example|
|redisKey|flights:BOM:DXB:2025-03-21:user123:8f3c0e1a76|
|BookingId|''Bkg-9834233'' |
|mysqlTx|UUID|
|ttl|300 sec|

===== Logging Standards =====

==== Log Levels ====

^Level^Usage|
|trace|dev deep debug|
|debug|engineering debug|
|info|business events|
|warn|recoverable risk|
|error|failure|
|fatal|crash events|

==== Required JSON Fields ====
 <font 9px/inherit;;inherit;;inherit>bash</font>
<code>

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

</code>

===== Pino Implementation =====

==== Install ====
 <font 9px/inherit;;inherit;;inherit>bash</font>

<code>
npm i pino pino-http pino-pretty

</code>

==== Logger Factory ( /src/infrastructure/logger/logger.ts ) ====
 <font 9px/inherit;;inherit;;inherit>ts</font>

<code>
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
});

</code>

==== HTTP Logger ( /src/infrastructure/logger/http-logger.ts ) ====
 <font 9px/inherit;;inherit;;inherit>ts</font>
<code>

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,
  })
});

</code>

==== Express Usage ====
 <font 9px/inherit;;inherit;;inherit>ts</font>
<code>

app.use(httpLogger);

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

</code>

==== Business Logging Example ====
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

==== OpenTelemetry Tracing ====

Should attach:

  * traceId
  * spanId

==== Benefits ====

  * distributed tracing
  * flame graphs
  * error attribution

<code>
Code to link trace → logs → DB query

</code>

===== Security & Compliance =====

**Never log:**
  * passwords
  * card numbers
  * tokens
  * PII

==== Jest Logger Tests ====
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

====== Error Handling Strategy ======

**1. Client Errors (4xx)**

^Code^Meaning|
|400|Bad Request/validation failure|
|401|unauthorized|
|404|cache expired|
|409|idempotency conflict|
|500|internal error|

**2. Server Errors (5xx)**

^Type^Source^Action|
|Dependency Failure|Redis/MySQL|Retry / Circuit Breaker|
|Timeout|3rd-party API|Fail fast|
|Internal Crash|unexpected bug|Log & alert|

**3. Business Errors**

^Example^Handling|
|Flight unavailable|409|
|Payment declined|422|
|Invalid state transition|409|

===== Recommended Placement =====

**1. ****Business / Domain Errors**

When business rule is violeted -
 <font inherit/inherit;;inherit;;#dddddd>/src/domain/errors</font>
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

**2. ****Application Errors**

Use-case level\\
Validation / workflow / orchestration

/src/application/errors
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

**3. ****Infrastructure Errors**

ONLY for wrapping technical failures

/src/infrastructure/errors
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

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

Example mapping:
 <font 9px/inherit;;inherit;;inherit>ts</font>

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

</code>

So the **API layer never leaks Redis internals.**


===== Error Flow (Best Practice) =====

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

</code>

final structure should look like

<code>
/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

</code>

**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