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

In a previously designed supply‑chain system the author describes services such as product, order, franchisee, store‑operation and work‑order, each with multiple user roles and two client apps (customer and employee).

The initial architecture follows a typical Spring Cloud gateway that handles routing, authentication, monitoring and rate‑limiting, but the author identifies two problems: unclear placement of interfaces used by both apps and tangled dependencies among services.

Case 1 shows interfaces being placed arbitrarily in store or work‑order services, leading to duplicated responsibilities. Case 2 illustrates a workflow that modifies several services (inventory, order status, work‑order) causing chaotic service‑to‑service calls.

To solve these issues the team introduces an API layer whose responsibilities are aggregation, distributed invocation and decoration, without its own database, delegating calls to backend services via Feign.

After adding the API layer the number of decisions about interface location drops and inter‑service dependencies are reduced to only the API layer calling backend services.

However, supporting multiple client types (App, H5, PC, mini‑program) introduces three new challenges: differing UI data needs, frequent minor field changes requiring fast client‑side adaptation, and increased version‑management complexity.

The solution is to adopt a Backend‑for‑Frontend (BFF) pattern, creating a dedicated API service per client that can be optimized and released independently, eliminating generic compatibility logic.

The final architecture combines a Spring Cloud Zuul gateway, per‑client BFF services, shared API services for common logic, and backend services with their own databases, with clear division of responsibilities between API teams and domain‑specific backend teams.

Gateway: Spring Cloud Zuul with ZooKeeper registration and Feign routing.

API service: Spring Web service that aggregates, calls distributed services and decorates data.

Backend service: Spring Web service with its own database and cache.

The article also discusses practical ways to handle code duplication across APIs, such as sharing common JARs, creating a CommonAPI service, or accepting limited duplication when maintenance cost is low.