🛍️ Kigalishopexpress BFF

Backend For Frontend · Marketplace Core Gateway

Powering the next-gen e-commerce experience for Kigalishopexpress.com — seamless API orchestration, aggregated responses, and frontend optimization layer.

📡 Server Information

marketplace-web-bff ● Active & Healthy

Version: 2.1.0

🖥️ Service Name:
KigaliShopExpress BFF Layer

🚪 Port:
5007

🌐 Environment:
production (staging-ready)

⚙️ Runtime:
Node.js + Express

📅 Deployed:
2025-04-17

🛡️ CORS Policy:
Enabled for trusted origins

💡 BFF Responsibilities:

Request aggregation, response shaping, authentication delegation, and section-based property data orchestration for frontend clients (React/Next.js).

🔗 REST API Endpoints

All endpoints are prefixed with /bff and designed specifically for the Kigalishopexpress frontend requirements. Each route returns optimized payloads, reducing client-side processing.

GET /health → Health check + BFF uptime & dependency status (Redis, upstream gateway).
GET /bff/property/sections/new-arrivals → Fetches aggregated "New Arrivals" section: products with images, pricing, and seller info from multiple microservices.
GET /bff/property/sections/trending → Trending products section based on real-time analytics and clickstream data.
GET /bff/property/sections/recommended → Personalized recommendations for logged-in users (leverages ML service).
POST /bff/user/wishlist/:id → Add/remove items to user wishlist, orchestrate between cart and user profile services.
GET /bff/checkout/summary → Combined cart, shipping, and tax info for checkout page (single aggregated payload).

📎 Example Response (New Arrivals)

{
  "status": "success",
  "section": "new_arrivals",
  "data": [
    { "id": "p101", "name": "Rwandan Coffee Beans", "price": 12.99, "image_url": "...", "seller": "Kigali Farmers Coop" },
    { "id": "p102", "name": "Handmade Agaseke Basket", "price": 24.50, "image_url": "...", "seller": "Women Craft Guild" }
  ],
  "cached": false,
  "timestamp": "2025-04-17T10:23:45Z"
}

🧠 Detailed Architecture: BFF Pattern for Kigalishopexpress

Why BFF? The Backend For Frontend pattern isolates frontend-specific concerns. Instead of forcing generic APIs, our BFF tailors responses for web clients, reduces over-fetching, and improves performance.

🌍 1. Client Layer React SPA / React.js (kigalishopexpress.com) → Makes requests to BFF instead of talking directly to microservices.

⚡ 2. BFF Layer (This Service) Orchestrates calls, merges data, adds caching, handles auth (JWT), and provides clean DTOs.

🚪 3. API Gateway Routes internal traffic, rate limiting, and service discovery (Consul/Eureka).

📦 4. Core Microservices Product Service, Inventory Service, User Service, Order Service, Recommendation Engine.

🗄️ 5. Data Stores MySQL (primary), Redis (caching & session), Elasticsearch (search).

🔁 6. Async Events Kafka / RabbitMQ for order updates, stock changes, and analytics pipelines.

📐 BFF Request Flow (Step by Step)

1. Browser → BFF (GET /bff/property/sections/new-arrivals)
2. BFF validates JWT token (if needed)
3. BFF concurrently calls:
   - Product Service (new arrivals IDs)
   - Image Service (product thumbnails)
   - Rating Service (average reviews)
4. BFF aggregates data & reshapes into frontend-friendly schema
5. BFF caches response for 60 seconds (Redis)
6. Returns JSON payload to client

✨ Benefits for Kigalishopexpress:

✅ Reduced network roundtrips (1 BFF call vs 4-5 direct calls)
✅ Tailored payload size for frontend performance (no unnecessary fields)
✅ Centralized error handling & resilience patterns (circuit breakers)
✅ Frontend team autonomy: BFF evolves independently from core domain services

⚙️ Environment Configuration

Current BFF runtime variables (simplified)

.env

# ============================================
# Kigalishopexpress BFF Environment Variables
# ============================================

# Server configuration
PORT=5007
NODE_ENV=production

# Upstream API Gateway endpoint
API_GATEWAY_URL=https://api.kigalishopexpress.com/gateway

# Redis connection for caching & sessions
REDIS_URL=redis://cache.kigalishopexpress:6379

# JWT secret for token verification (frontend tokens)
JWT_SECRET=your_super_secret_key_rotate_me

# Service timeouts (ms)
PRODUCT_SERVICE_TIMEOUT=2000
RECOMMENDATION_TIMEOUT=1500

# Feature flags
ENABLE_RESPONSE_COMPRESSION=true
CACHE_TTL_SECONDS=60

📌 Note: Multi-line comments in .env are not natively supported, but we prefix each line with # for readability — this block documents all required keys.

📊 Tech Stack & Dependencies

Node.js v20+ Express.js Axios (HTTP client) Redis (caching) Winston (logging) JWT (auth delegation) PM2 (process mgr)

🚦 Health & Monitoring

/health endpoint returns detailed service status, connectivity to API Gateway, and Redis availability. Integrated with Prometheus metrics.