gRPC and arch diagram

API-gateways.md

@@ -1,3 +1,15 @@
-For detailed info about "Implementing API Gateways with Ocelot" as implemented in eShopOnContainers, check out the following blog post:
+# API Gateways
 
-<https://blogs.msdn.microsoft.com/cesardelatorre/2018/05/15/designing-and-implementing-api-gateways-with-ocelot-in-a-microservices-and-container-based-architecture/>
+eShopOnContainer use 4 API Gateways that implement the BFF pattern. Overall architecture is:
+
+![Overall architecture of eShop](./images/Architecture/eshop-arq.png)
+
+The image above is the architecture when running eShopOnContainers on Kubernetes with Service Mesh enabled. If Service Mesh is disabled all the "Linkerd" containers do not exist and if running outside Kubernetes the "Ingress controller" do not exists and you access directly to API Gateways.
+
+In this architecture the 4 blue boxes in the column labelled as "eShop Ingress" are the four BFFs.
+
+Currently they are implemented using [Envoy](https://www.envoyproxy.io/). Each BFF provides a unique entrypoint for its clients and then forwards the call to the specific microservice or the custom aggregator.
+
+The communication between BFF and the microservices is always using HTTP/REST. This could change in the future by using gRPC from the BFF to the microservices, while mantaining a HTTP/REST façade from the BFFs to the clients.
+
+**Note**: The communication between the aggregators and the microservices is using gRPC, but between the BFFs and the aggregators is still HTTP/REST.

_Sidebar.md

@@ -22,6 +22,7 @@
 - [Application](Explore-the-application)
 - [Code](Explore-the-code)
   - [Simplified CQRS & DDD](Simplified-CQRS-and-DDD)
+  - [gRPC](gRPC)
   - [API gateways](API-gateways)
   - [Webhooks](Webhooks)
   - [Azure Key Vault](Azure-Key-Vault)

gRPC.md

@@ -0,0 +1,25 @@
+# gRPC
+
+One of the big news on netcore 3.0 is the native support for gRPC. eShopOnContainers makes use of gRPC for internal microservice-to-microservice synchronous communication. Note that, in eShop most of the communication between microservices is decoupled and asynchronous using an Event Bus (we support RabbitMQ or Azure Service Bus).
+
+In current implementation use of gRPC is limited to the communication between aggregators and micro services. We have following synchronous communications between services in eShop:
+
+1. External clients (i. e. Xamarin App or Browser) to Api Gateways (BFFs): Use HTTP/REST
+2. From BFFs to Aggregators: Use HTTP/REST
+    * This is basically a request forward. Based on route request is forwarded from the BFF to the aggregator. This is performed for "logically complex" requests, when a single client call involves various microservices that are coordinated from the aggregator.
+3. From BFFs to microservices: Use HTTP/REST
+    * This is basically a request forward. Based on route request is forwarded from the BFF to the internal microservice. This is performed for simple CRUD requests.
+4. From Aggregators to microservices: Use gRPC
+
+Currently we are not transcoding from gRPC to HTTP/REST. This would allow use gRPC from the BFFs to both aggregators and microservices while keeping a HTTP/REST interfaceto the clients. This gRPC<->HTTP/REST translation could be done at BFF level.
+
+Following microservices expose gRPC endpoints:
+
+* Ordering API
+* Catalog API
+* Basket API
+
+And following BFFs are gRPC clients:
+
+* Mobile Shopping
+* Web Shopping