Differences

This shows you the differences between two versions of the page.

--- flight_booking_bff [2025/12/31 09:11] – [OpenTelemetry Tracing] pradnya
+++ flight_booking_bff [2026/01/24 05:44] (current) – [Error Handling Strategy] madan
@@ Line 15: / Line 15: @@
 ==== Key Services / Core Components ====
-^Service^Responsibility|
+^Service^Responsibility^Local Port|
-|**API Gateway / BFF (Node.js)** |Single entry point for UI|
+|**API Gateway / BFF (Node.js)** |Single entry point for UI|4000|
-|**Auth Service** |Issues & validates tokens|
+|**Auth Service** |Issues & validates tokens|4001|
-|**Flight Service** |Calls supplier API + Redis cache|
+|**Flight Service** |Calls supplier API + Redis cache|4002|
-|**Booking Service (MySQL)** |Stores booking data|
+|**Booking Service (MySQL)** |Stores booking data|4003|
-|**Payment Service** |Payment initiation + webhooks|
+|**Payment Service** |Payment initiation + webhooks|4004|
 ==== Observability Stack ====
-  *
+  * **Pino**
+  * **Pino-Http**
-**Pino**
+  * **OpenTelemetry**
-  *
+  * **Cloud Logging (ELK / CloudWatch / Loki)**
-**Pino-Http**
-  *
-**OpenTelemetry**
-  *
-**Cloud Logging (ELK / CloudWatch / Loki)**
 === Token Flow Diagram ===
 <code>
@@ Line 71: / Line 64: @@
 <code>
 Search Flights → Cache Results
-Select Flight → Create Order
+Select Flight → Create booking
 Initiate Payment → Payment Gateway
-Webhook Received → Confirm Order
+Webhook Received → Confirm booking
 Persist in MySQL → Send Confirmation
@@ Line 80: / Line 73: @@
 ===== 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/
+ │   ├ middlewares/
+ │   └ errors/
  ├ domain/
  │   ├ entities/
  │   ├ services/
- │   └ repositories/
+ │   ├ repositories/
+ │   └ errors/
  ├ infrastructure/
  │   ├ db/
  │   ├ redis/
  │   ├ logger/
- │   └ http/
+ │   ├ http/
+ │   └ errors/
  └ tests/
 </code>
 ===== MySQL — Connection Pool =====
@@ Line 334: / Line 339: @@
       * trace id
   * Support dashboards & SLIs
 ===== Correlation ID Strategy =====
@@ Line 374: / Line 378: @@
 ==== Required JSON Fields ====
  <font 9px/inherit;;inherit;;inherit>bash</font>
 <code>
 timestamp
 service
@@ Line 390: / Line 394: @@
 </code>
 ===== Pino Implementation =====
@@ Line 397: / Line 400: @@
  <font 9px/inherit;;inherit;;inherit>bash</font>
-<code>npm i pino pino-http pino-pretty
+<code>
+npm i pino pino-http pino-pretty
 </code>
@@ Line 416: / Line 421: @@
 </code>
 ==== HTTP Logger ( /src/infrastructure/logger/http-logger.ts ) ====
  <font 9px/inherit;;inherit;;inherit>ts</font>
 <code>
@@ Line 437: / Line 440: @@
 </code>
 ==== Express Usage ====
  <font 9px/inherit;;inherit;;inherit>ts</font>
 <code>
@@ Line 452: / Line 453: @@
 </code>
 ==== Business Logging Example ====
@@ Line 459: / Line 459: @@
 <code>
 req.log.info({
-  orderId,
+  bkgId,
   redisKey,
-  step: 'order-confirmation'
+  step: 'booking-confirmation'
-}, 'Order confirmed');
+}, 'Booking confirmed');
 </code>
 ==== OpenTelemetry Tracing ====
@@ Line 473: / Line 472: @@
   * traceId
   * spanId
 ==== Benefits ====
@@ Line 481: / Line 479: @@
   * error attribution
-<code>Code to link trace → logs → DB query
+<code>
+Code to link trace → logs → DB query
 </code>
@@ Line 495: / Line 495: @@
  <font 9px/inherit;;inherit;;inherit>ts</font>
-<code>describe('logger', () => { \\
+<code>
-  it('logs JSON structure', () => { \\
+describe('logger', () => {
-    const log = logger.info({ test: true }, 'hello'); \\
+  it('logs JSON structure', () => {
-    expect(log).toBeDefined(); \\
+    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