Merge pull request #330 from Accenture/284-document-sync-async-http-to-kafka

Improve README and feature docs

Author: kevinbader

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added possibility to set response code for `response_from` messages in reverse proxy (`kafka` and `http_async`). [#321](https://github.com/Accenture/reactive-interaction-gateway/pull/321)
 - Added new version - `v3` - for internal endpoints to support response code in the `/responses` endpoint
 - Added Helm v3 template to the `deployment` folder [#288](https://github.com/Accenture/reactive-interaction-gateway/issues/288)
+- Added detailed features summary on the website with architecture diagrams. [#284](https://github.com/Accenture/reactive-interaction-gateway/issues/284)
 
 ### Changed
 
@@ -31,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ```
 
   More information, follow the [deployment Readme](./deployment/README.md). [#319](https://github.com/Accenture/reactive-interaction-gateway/issues/319)
+- make README smaller, easier to read and highlight features. [#284](https://github.com/Accenture/reactive-interaction-gateway/issues/284)
 
 ### Fixed
 

CONTRIBUTING.md

@@ -7,6 +7,20 @@ in the [Accenture Organization](https://github.com/accenture) on GitHub. These a
 guidelines, not rules. Use your best judgment, and feel free to propose changes to this document
 in a pull request.
 
+## TL;DR
+
+- **Use issues for everything.**
+- For a small change, just send a PR.
+- For bigger changes open an issue for discussion before sending a PR.
+- PR should have:
+  - Test case
+  - Documentation (e.g., moduledoc, developer's guide, operator's guide)
+  - Changelog entry
+- You can also contribute by:
+  - Reporting issues
+  - Suggesting new features or enhancements
+  - Improve/fix documentation
+
 ## Code of Conduct
 
 This project and everyone participating in it is governed by our

README.md

@@ -2,92 +2,39 @@
 
 # RIG - Reactive Interaction Gateway
 
-Create low-latency, interactive user experiences for stateless microservices.
+Makes frontend<->backend communication reactive and event-driven.
 
 [![Build Status](https://travis-ci.org/Accenture/reactive-interaction-gateway.svg?branch=master)](https://travis-ci.org/Accenture/reactive-interaction-gateway)
 [![DockerHub](https://img.shields.io/docker/pulls/accenture/reactive-interaction-gateway)](https://hub.docker.com/r/accenture/reactive-interaction-gateway)
-[![Slack](https://rig-slackin.herokuapp.com/badge.svg)](https://rig-slackin.herokuapp.com)
-
-Take a look at the [documentation](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html) and get in touch with us on [Slack](https://rig-slackin.herokuapp.com)!
-
-- [About](#about)
-- [Getting Started](#getting-started)
-  - [API Documentation](#api-documentation)
-  - [Metrics](#metrics)
-- [Contribute](#contribute)
-- [License](#license)
-- [Acknowledgments](#acknowledgments)
 
 ## About
 
-How RIG makes asynchronous backend<->frontend communication easier:
-
-- RIG takes care of client connection state so you don't have to.
-- RIG picks up back-end events and forwards them to clients based on subscriptions.
-- RIG forwards client requests to backend services either synchronously or asynchronously.
-
-Built on open standards, RIG is very easy to integrate – and easy to _replace_ – which means low-cost, low-risk adoption. Unlike other solutions, RIG does not leak into your application – no libraries or SDKs required.
-
-Features:
-
-- Easy to use and scalable by design:
-  - Supports tens of thousands stable connections per node even on low-end machines.
-  - Easy to add additional nodes.
-  - Built on the battle-proven [Erlang/OTP](http://www.erlang.org/) distribution model.
-  - Only uses in-memory data structures - no external dependencies to configure or scale.
-- Connect using standard protocols:
-  - Firewall friendly and future proof using Server-Sent Events (SSE)
-    - [HTML5 standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events).
-    - Regular HTTP requests, so no issues with proxy servers or firewalls.
-    - Connection multiplexing with HTTP/2 out of the box.
-    - SSE implementation (browser) keeps track of connection drops and restores the connection automatically.
-    - Polyfills available for older browsers.
-  - WebSocket connections are supported, too.
-  - HTTP long polling for situations where SSE and WS are not supported.
-- Publish events from various sources:
-  - Kafka
-  - NATS
-  - Amazon Kinesis
-  - or publish via HTTP
-- Convert a HTTP request to a message for asynchronous processing:
-  - produce to Kafka topic, optionally wait for the result on another Kafka topic
-  - produce to a NATS topic, optionally using NATS request-response to wait for the result
-  - produce to Amazon Kinesis
-- Uses the CNCF [CloudEvents specification](https://cloudevents.io/).
-- Flexible event subscription model based on event types.
-- Use existing services for authentication and authorization of users and subscriptions.
-- JWT signature verification for APIs as a simple authentication check.
-- Session blacklist with immediate session invalidation.
-
-For more details take a look at the [documentation](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html).
-
-## Getting Started
+The Reactive Interaction Gateway (RIG) is the glue between your client (frontend) and your backend. It makes communication between them easier by (click the links to learn more)
 
-Take a look at the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html).
+- picking up backend events and forwarding them to clients based on subscriptions: this makes your frontend apps **reactive and eliminates the need for polling**. You can do this
+  - [asynchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#picking-up-backend-events-and-forwarding-them-to-clients-based-on-subscriptions#asynchronously) - using Kafka, Nats or Kinesis.
+  - [synchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#picking-up-backend-events-and-forwarding-them-to-clients-based-on-subscriptions#synchronously) - if you don't want to manage a (potentially complex) message broker system like Kafka.
+- forwarding client requests to backend services either synchronously, asynchronously or a mix of both:
+  - [synchronously](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#synchronously) - if requests are being sent synchronously, RIG acts as a reverse proxy: RIG forwards the request to an HTTP endpoint of a backend service, waits for the response and sends it to the client.
+  - [asynchronously - fire&forget](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#asynchronously---fireforget) - RIG transforms a HTTP request to a message for asynchronous processing and forwards it to the backend asynchronously using either Kafka, NATS or Amazon Kinesis.
+  - [synchronously with asynchronous response](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#synchronously---asnychronous-response) - a pseudo-synchronous request: RIG forwards the client request to the backend synchronously via HTTP and waits for the backend response by listening to Kafka/NATS and forwarding it to the still open HTTP connection to the frontend.
+  - [asynchronously with asynchronous response](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#asynchronously---asnychronous-response) - a pseudo-synchronous request: RIG forwards the client request to the backend asynchronously via Kafka or NATS and waits for the backend response by listening to Kafka/NATS and forwarding it to the still open HTTP connection to the frontend.
 
-### API Documentation
+Built on open standards, RIG is very easy to integrate – and easy to replace – which means low-cost, low-risk adoption. Unlike other solutions, RIG does not leak into your application – no libraries or SDKs required. Along with handling client requests and publishing events from backend to the frontend, RIG provides [many out-of-the-box features](https://accenture.github.io/reactive-interaction-gateway/docs/features.html#out-of-the-box-features).
 
-RIG exposes its API documentation on its API endpoint under [/swagger-ui](http://localhost:4010/swagger-ui). For integration into an existing swagger UI, the related JSON document can either be [retrieved at runtime](http://localhost:4010/swagger-ui/rig_api_swagger.json) or [found on disk](./priv/static/rig_api_swagger.json) after compiling RIG at least once.
+This is just a basic summary of what RIG can do. There is a comprehensive documentation available on our [website](https://accenture.github.io/reactive-interaction-gateway/docs/intro.html). If you have any unanswered question, check out the [FAQ](https://accenture.github.io/reactive-interaction-gateway/docs/faq.html) section to get them answered.
 
-### Metrics
-
-RIG exposes Metrics in [Prometheus](https://prometheus.io/) format on its API endpoint under [/metrics](http:localhost:4010/metrics)
+## Getting Started
 
-## Contribute
+- Take a look at the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html) for a simple walkthrough using docker
+- For deploying RIG on Kubernetes, check out the [Kubernetes deployment instructions](https://github.com/Accenture/reactive-interaction-gateway/tree/284-document-sync-async-http-to-kafka/deployment)
 
-- **Use issues for everything.**
-- For a small change, just send a PR.
-- For bigger changes open an issue for discussion before sending a PR.
-- PR should have:
-  - Test case
-  - Documentation (e.g., moduledoc, developer's guide, operator's guide)
-  - Changelog entry
-- You can also contribute by:
-  - Reporting issues
-  - Suggesting new features or enhancements
-  - Improve/fix documentation
+## Get Involved
 
-See the [developer's guide](https://accenture.github.io/reactive-interaction-gateway/docs/rig-dev-guide.html) and [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+- discuss RIG on [Slack](https://rig-slackin.herokuapp.com)
+- Follow us on [Twitter](https://twitter.com/reactivegateway)
+- Start contributing: refer to our [contributing guide](./CONTRIBUTING.md)
+- Develop RIG: refer to our [developer's guide](https://accenture.github.io/reactive-interaction-gateway/docs/rig-dev-guide.html)
 
 ## License
 
@@ -105,5 +52,3 @@ Kudos to these awesome projects:
 - Phoenix Framework
 - Brod
 - Distillery
-
-.

ct.yaml

@@ -2,4 +2,3 @@
 remote: origin
 chart-dirs:
   - deployment
-debug: true

deployment/README.md

@@ -20,8 +20,11 @@ Check out the [Helm v2 README](./reactive-interaction-gateway-helm-v2/README.md)
 kubectl apply -f kubectl/rig.yaml
 ```
 
+
 ## Some Additional information
 
+Check out the [getting-started tutorial](https://accenture.github.io/reactive-interaction-gateway/docs/tutorial.html), the [examples](https://accenture.github.io/reactive-interaction-gateway/docs/examples.html) and the [features](https://accenture.github.io/reactive-interaction-gateway/docs/features.html) for more information what you can do with RIG.
+
 ### Communication
 
 Both `kubectl` and `helm` deploy bunch of Kubernetes resources:

docs/api-documentation.md

@@ -0,0 +1,7 @@
+---
+id: api-documentation
+title: API Documentation
+sidebar_label: API Documentation
+---
+
+RIG exposes its API documentation on its API endpoint under [/swagger-ui](http://localhost:4010/swagger-ui). For integration into an existing swagger UI, the related JSON document can either be [retrieved at runtime](http://localhost:4010/swagger-ui/rig_api_swagger.json) or found on disk at `priv/static/rig_api_swagger.json` after compiling RIG at least once.

docs/architecture.md

@@ -21,7 +21,7 @@ Why not introduce (connection) state for microservices? Two reasons. First, it m
 
 ## Event-Driven Architecture and the UI
 
-Forwarding events to frontends enables and event-driven UX design, effectively extending the idea of [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) to the UI.
+Forwarding events to frontends enables an event-driven UX design, effectively extending the idea of [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) to the UI.
 
 We believe that hiding asynchronism by turning it into a fake synchronous process is an anti-pattern. For example, sending money from one bank account to another doesn't happen instantaneously, but with at least two events: "transfer requested" and "transfer completed" (or "transfer failed"). Acknowledging this when designing the UI leads to a more natural user experience and less loading indicators.