Designing an API Layer and BFF Architecture for a Large-Scale Supply Chain System

In a previously designed supply‑chain system that includes products, sales orders, franchisees, store operations, and work orders, multiple user roles (headquarters product management, store management, franchise employees, store staff) and two client apps (customer‑facing and employee‑facing) are involved.

The overall architecture consists of a gateway layer responsible for routing, authentication, monitoring, and rate‑limiting/fuse‑breaking, as illustrated in the first diagram.

Case One

Many UI pages need to display data from several services (e.g., work order count, recent orders, low‑stock items). The team struggled with deciding which service should host the interfaces for the two client apps, leading to unclear responsibilities.

They eventually placed the first interface in the store service and the second interface in the work‑order service, as shown in the following diagrams.

Case Two

A single user action, such as submitting a work order, often requires updates across multiple services (inventory, sales order status, work order). This caused tangled inter‑service dependencies, depicted in the third diagram.

To address both problems, an API layer was introduced.

API Layer

The API layer fulfills three main needs: aggregation (combining data from multiple backend services), distributed calls (sequentially invoking several services), and decoration (modifying or filtering returned data).

By inserting this layer between clients and backend services, the architecture (fourth diagram) shows that all requests pass through the gateway, then the shared API layer, which has no database of its own but orchestrates calls to other services.

Client Adaptation Issues

Different clients (App, H5, PC, mini‑program) have varying UI requirements, leading to three problems: divergent data needs per client, frequent minor changes requiring rapid releases, and increased complexity in the API layer to maintain compatibility.

The proposed solution is to adopt a Backend‑for‑Frontend (BFF) pattern, where each client has its own dedicated API service, as illustrated in the fifth diagram.

Technical Implementation

The system is built on Spring Cloud (Zuul gateway, Feign clients). The gateway routes requests, the API services act as Spring Web services without databases, and the backend services are standard Spring Web services with their own databases and caches.

Resolving API Code Duplication

Duplicate logic across PC and App APIs can be handled in three ways: sharing a JAR, extracting a CommonAPI service, or keeping the duplication if the maintenance cost is low. The team ultimately retained the simple proxy APIs.

Team Division

Dedicated API development teams manage the API services, while backend services are divided into domain‑specific groups, ensuring clear ownership and reducing overlapping work.

Conclusion

The article concludes with a call for readers to follow the author’s public account for PDF versions of related Spring Cloud, Spring Boot, and MyBatis advanced guides.