๐Ÿ• Menu API โ€“ Lowโ€Level Design (LLD) - ashwani-cse/next-gen-pizza-backend GitHub Wiki

๐Ÿ“Œ Overview

This document outlines the Low-Level Design (LLD) for the Menu API, which powers a cloud-native, real-time, and scalable pizza ordering platform. The API is optimized for:

  • โšก High-speed reads
  • ๐Ÿ”„ Real-time menu updates
  • ๐Ÿ“Š Structured analytics
  • ๐Ÿš€ Future extensibility

๐Ÿ“‚ Module Breakdown

1. API Layer (Spring WebFlux)

Component Description
Controller MenuController.java โ€“ Exposes REST endpoints
Service MenuService.java โ€“ Core business logic
DTOs MenuItemDTO.java, CategoryDTO.java โ€“ Request/response models
Mapper MenuMapper.java โ€“ Converts between DTOs and domain objects

2. Caching Layer (Redis using Lettuce / Spring Data Redis)

Operation Details
Read Cache Keys: menu::all, menu::{id}
TTL 15 minutes (configurable)
Invalidation Triggered on any update (POST, PUT, DELETE)

3. Firestore Integration (Spring Cloud GCP Firestore)

Collection Structure
menus Document ID: {menuId}Fields: categories โ†’ List of categories and nested menu items
Updates Real-time listener or trigger-based via GCP Pub/Sub

4. PostgreSQL Sync

Table Schema
menu_items id, name, category_id, price, version, created_at
categories id, name, menu_id
Sync Logic Pub/Sub consumer transforms Firestore payloads to RDBMS models

5. Messaging Bus (GCP Pub/Sub)

Topic Purpose
menu-updates Broadcasts changes from Firestore
menu-sync-failure Captures failed sync events for troubleshooting
Subscriptions Workers subscribe to process PostgreSQL syncs

6. Deployment (Cloud Run / GKE)

Aspect Details
Container Dockerized Spring Boot application
Configuration Environment managed via GCP Secret Manager / ConfigMaps
Auto-scaling Based on CPU usage and concurrent request count (Cloud Run setup)

๐Ÿ” Endpoint Workflow

๐Ÿ‘ฅ GET /menu

Client
   โ†“
API Gateway
   โ†“
MenuController
   โ†“
Redis Cache
   โ†“ MISS
Firestore โ†’ Redis SET
   โ†“
Response to Client

๐Ÿง  Error Handling & Resilience

Layer Strategy
API Exception handlers with structured JSON errors
Firestore Retry template with exponential backoff
Pub/Sub DLQ (Dead Letter Queue) for failed sync messages
PostgreSQL Transaction rollback on write failure

๐Ÿงช Sample Data Structures

Firestore Document โ€“ menus/{menuId}

{
  "menuId": "menu123",
  "categories": [
    {
      "id": "cat001",
      "name": "Veg Pizza",
      "items": [
        {
          "id": "item001",
          "name": "Farmhouse",
          "price": 299
        }
      ]
    }
  ],
  "version": 3
}

๐Ÿ—ƒ๏ธ PostgreSQL Table: menu_items

id name category_id price version created_at
1 Farmhouse cat001 299 3 timestamp

๐Ÿ” Observability

Metric Tool Threshold
Redis Miss Rate Cloud Monitoring > 20%
Firestore Latency Cloud Trace > 500ms
Pub/Sub Backlog Cloud Monitoring > 100 messages
Sync Failure Custom logs > 1 in 10 min
Error Rate API Gateway Logs > 5%

๐Ÿ”ฎ Extensibility Guidelines

Feature Strategy
Multi-zone pricing Add zonePrices map in Firestore documents
Localization Add labels: { en, hi, ... } in item
Versioning Use version field + soft delete pattern
Scheduled menu push Use Cloud Scheduler + Pub/Sub trigger

โœ… Summary

Use Case Stack
High-Speed Read Redis + Firestore
Real-Time Update Firestore + Pub/Sub
Reporting PostgreSQL
Dashboard (Future) BigQuery
Deployment GCP Cloud Run / GKE