README: add screenshots, diagrams, features list

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

README.md

@@ -1,13 +1,71 @@
-# Microservices demo
+# Hipster Shop: Cloud-Native Microservices Demo Application
 
 This project contains a 10-tier microservices application. The application is a
-web-based e-commerce app called “Hipster Shop” where users can browse items,
+web-based e-commerce app called **“Hipster Shop”** where users can browse items,
 add them to the cart, and purchase them.
 
-Google has used this application to demonstrate Kubernetes, GKE, Istio,
-Stackdriver, gRPC and similar cloud-native technologies.
+**Google uses this application to demonstrate Kubernetes, GKE, Istio,
+Stackdriver, gRPC** and similar cloud-native technologies nowadays.
 
-### Running locally
+## Screenshots
+
+| Home Page | Checkout Screen |
+|-----------|-----------------|
+| [![Screenshot of store homepage](./img/hipster-shop-frontend-1.png)](./img/hipster-shop-frontend-1.png) | [![Screenshot of checkout screen](./img/hipster-shop-frontend-2.png)](./img/hipster-shop-frontend-2.png) |
+
+## Service Architecture
+
+**Hipster Shop** is composed of many microservices written in different
+languages that talk to each other over gRPC.
+
+[![Architecture of
+microservices](./img/architecture-diagram.png)](./img/architecture-diagram.png)
+
+Find **Protocol Buffers Descriptions** at the [`./pb` directory](./pb).
+
+| Service | Language | Description |
+|---------|----------|-------------|
+| [frontend](./src/frontend) | Go | Exposes an HTTP server to serve the website. Does not require signup/login and generates session IDs for all users automatically. |
+| [cartservice](./src/cartservice) |  C# | Stores the items in the user's shipping cart in Redis and retrieves it. |
+| [productcatalogservice](./src/productcatalogservice) | Go | Provides the list of products from a JSON file and ability to search products and get individual products. |
+| [currencyservice](./src/currencyservice) | Node.js | Converts one money amount to another currency.  Uses real values fetched from European Central Bank. It's the highest QPS service. |
+| [paymentservice](./src/paymentservice) | Node.js | Charges the given credit card info (hypothetically😇) with the given amount and returns a transaction ID. |
+| [shippingservice](./src/shippingservice) | Go | Gives shipping cost estimates based on the shopping cart. Ships items to the given address (hypothetically😇) |
+| [emailservice](./src/emailservice) | Python | Sends users an order confirmation email (hypothetically😇). |
+| [checkoutservice](./src/checkoutservice) | Go | Retrieves user cart, prepares order and orchestrates the payment, shipping and the email notification. |
+| [recommendationservice](./src/recommendationservice) | Python | Recommends other products based on what's given in the cart. |
+| [loadgenerator](./src/loadgenerator) | Python/Locust | Continuously sends requests imitating realistic user shopping flows to the frontend. |
+
+
+## Features
+
+- **[Kubernetes](https://kubernetes.io)/[GKE](https://cloud.google.com/kubernetes-engine/):**
+  The app is designed to run on Kubernetes (both locally on "Docker for
+  Desktop", as well as on the cloud with GKE).
+- **[gRPC](https://grpc.io):** Microservices use a high volume of gRPC calls to
+  communicate to each other.
+- **[Istio](https://istio.io):** Application works on Istio service mesh.
+- **[OpenCensus](https://opencensus.io/) Tracing:** Most services are
+  instrumented using OpenCensus trace interceptors for gRPC/HTTP.
+- **[Stackdriver APM](https://cloud.google.com/stackdriver/):** Many services
+  are instrumented with **Profiling**, **Tracing** and **Debugging**. In
+  addition to these, using Istio enables features like Request/Response
+  **Metrics** and **Context Graph** out of the box. When it is running out of
+  Google Cloud, this code path remains inactive.
+- **[Skaffold](https://github.com/GoogleContainerTools/skaffold):** Application
+  is deployed to Kubernetes with a single command using Skaffold.
+- **Synthetic Load Generation:** The application demo comes with a background
+  job that creates realistic usage patterns on the website using
+  [Locust](https://locust.io/) load generator.
+
+## Installation
+
+> **Note:** that the first build can take up to 20-30 minutes. Consequent builds
+> will be faster.
+
+### Option 1: Running locally with “Docker for Desktop”
+
+> 💡 Recommended if you're planning to develop the application.
 
 1. Install tools to run a Kubernetes cluster locally:
 
@@ -28,7 +86,9 @@ Stackdriver, gRPC and similar cloud-native technologies.
    application frontend should be available at http://localhost:80 on your
    machine.
 
-### Setup on GKE
+### Option 2: Running on Google Kubernetes Engine (GKE)
+
+> 💡  Recommended for demos and making it available publicly.
 
 1. Install tools specified in the previous section (Docker, kubectl, skaffold)
 
@@ -38,7 +98,7 @@ Stackdriver, gRPC and similar cloud-native technologies.
 1. Enable Google Container Registry (GCR) on your GCP project:
 
        gcloud services enable containerregistry.googleapis.com
-    
+
 1. Configure docker to authenticate to GCR:
 
        gcloud auth configure-docker -q
@@ -52,14 +112,14 @@ Stackdriver, gRPC and similar cloud-native technologies.
 1. Run `skaffold run`. This builds the container
    images, pushes them to GCR, and deploys the application to Kubernetes.
 
-1.  Find the IP address of your application:
+1.  Find the IP address of your application then visit the application on your
+    browser to confirm installation.
 
         kubectl get service frontend-external
 
-    then visit the application on your browser to confirm
-    installation.
+### (Optional) Deploying on a Istio-installed cluster
 
-### Istio Deployment
+> If you followed steps above, run `skaffold delete` to delete what's deployed.
 
 1. Create a GKE cluster.
 
@@ -71,14 +131,19 @@ Stackdriver, gRPC and similar cloud-native technologies.
 
        kubectl label namespace default istio-injection=enabled
 
-4. Deploy the application with.
+4. Deploy the application with `skaffold run`.
 
 5. Apply the manifests in [`./istio-manifests`](./istio-manifests) directory.
 
        kubectl apply -f ./istio-manifests
 
+    This is required only once.
+
 6. Run `kubectl get pods` to see pods are in a healthy and ready state.
 
+1. Find the IP address of your istio gateway Ingress or Service, and visit the
+   application.
+
 ---
 
 This is not an official Google project.