Conceptual docs updates (#845)

* Update title

* Update to conceptual docs

daprdocs/content/en/docs/concepts/_index.md

@@ -2,5 +2,5 @@
 title: "Dapr Concepts"
 linkTitle: "Concepts"
 weight: 10
-description: "Learn about Dapr, including what it aims to do and how it is built."
+description: "Learn about Dapr including its main features and capabilities"
 ---

daprdocs/content/en/docs/concepts/building-blocks.md

@@ -1,6 +1,28 @@
 ---
-title: "Dapr Building Blocks"
+title: "Building blocks"
 linkTitle: "Building Blocks"
 weight: 200
-description: "HTTP or gRPC APIs that can be called from user code"
----
+description: "Modular best practices accessible over standard HTTP or gRPC APIs"
+---
+
+A [building block](/docs/concepts/architecture/building-blocks) is as an HTTP or gRPC API that can be called from your code and uses one or more Dapr components. 
+
+Building blocks address common challenges in building resilient, microservices applications and codify best practices and patterns. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
+
+The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks' capability.
+
+<img src="/images/concepts-building-blocks.png" width=250>
+  
+The following are the building blocks provided by Dapr:
+
+<img src="/images/building_blocks.png" width=1000>
+
+| Building Block | Endpoint | Description |
+|----------------|----------|-------------|
+| [**Service-to-Service Invocation**]({{<ref "service-invocation-overview.md">}}) | `/v1.0/invoke` | Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
+| [**State Management**] ({{<ref "service-invocation-overview.md">}} ) | `/v1.0/state` | Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence.
+| [**Publish and Subscribe**]({{<ref "service-invocation-overview.md">}}) | `/v1.0/publish` `/v1.0/subscribe`|  Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
+| [**Resource Bindings**]({{<ref "service-invocation-overview.md">}}) | `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the  Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
+| [**Actors**]({{<ref "service-invocation-overview.md">}}) | `/v1.0/actors` |  An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See * [Actor Overview](./actors#understanding-actors)
+| [**Observability**]({{<ref "service-invocation-overview.md">}}) | `N/A` |  Dapr system components and runtime emit metrics, logs, and traces to debug, operate and monitor Dapr system services, components and user applications.
+| [**Secrets**]({{<ref "service-invocation-overview.md">}}) | `/v1.0/secrets` | Dapr offers a secrets building block API and integrates with secret stores such as Azure Key Vault and Kubernetes to store the secrets. Service code can call the secrets API to retrieve secrets out of the Dapr supported secret stores.

daprdocs/content/en/docs/concepts/components.md

@@ -1,24 +1,24 @@
 ---
-title: "Dapr Components"
+title: "Components"
 linkTitle: "Components"
-weight: 100
-description: "Modular pieces of functionality used in Dapr."
+weight: 300
+description: "Modular functionality used by building blocks and applications"
 ---
 
 Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition.  All of the components are pluggable so that you can swap out one component with the same interface for another. The [components contrib repo](https://github.com/dapr/components-contrib) is where you can contribute implementations for the component interfaces and extends Dapr's capabilities.
   
- A building block can use any combination of components. For example the [actors](./actors) building block and the state management building block both use state  components.  As another example, the pub/sub building block uses [pub/sub](./publish-subscribe-messaging/README.md) components.
+ A building block can use any combination of components. For example the [actors]({{<ref "service-invocation-overview.md">}}) building block and the [state management]({{<ref "service-invocation-overview.md">}}) building block both use [state components](https://github.com/dapr/components-contrib/tree/master/state).  As another example, the [pub/sub]({{<ref "service-invocation-overview.md">}}) building block uses [pub/sub](https://github.com/dapr/components-contrib/tree/master/pubsub) components.
 
  You can get a list of current components available in the current hosting environment using the `dapr components` CLI command.
 
  The following are the component types provided by Dapr:
 
-* [Service discovery](https://github.com/dapr/components-contrib/tree/master/nameresolution)
-* [State](https://github.com/dapr/components-contrib/tree/master/state)
-* [Pub/sub](https://github.com/dapr/components-contrib/tree/master/pubsub)
 * [Bindings](https://github.com/dapr/components-contrib/tree/master/bindings)
+* [Pub/sub](https://github.com/dapr/components-contrib/tree/master/pubsub)
 * [Middleware](https://github.com/dapr/components-contrib/tree/master/middleware)
+* [Service discovery name resolution](https://github.com/dapr/components-contrib/tree/master/nameresolution)
 * [Secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
+* [State](https://github.com/dapr/components-contrib/tree/master/state)
 * [Tracing exporters](https://github.com/dapr/components-contrib/tree/master/exporters)
 
 ### Service invocation and service discovery components

daprdocs/content/en/docs/concepts/configuration.md

@@ -1,18 +1,13 @@
 ---
-title: "Dapr Configurations"
+title: "Configuration"
 linkTitle: "Configuration"
-weight: 30
+weight: 400
+description: "Change the behavior of Dapr sidecars or globally on Dapr system services"
 ---
 
 Dapr configurations are settings that enable you to change the behavior of individual Dapr application sidecars or globally on the system services in the Dapr control plane.
 An example of a per Dapr application sidecar setting is configuring trace settings. An example of a Dapr control plane setting is mutual TLS which is a global setting on the Sentry system service.   
 
-- [Setting self hosted sidecar configuration](#setting-self-hosted-sidecar-configuration)
-- [Setting Kubernetes sidecar configuration](#setting-kubernetes-sidecar-configuration)
-- [Sidecar configuration settings](#sidecar-configuration-settings)
-- [Setting Kubernetes control plane configuration](#kubernetes-control-plane-configuration)
-- [Control plane configuration settings](#control-plane-configuration-settings)
-
 ## Setting self hosted sidecar configuration
 In self hosted mode the Dapr configuration is a configuration file, for example `config.yaml`. By default the Dapr sidecar looks in the default Dapr folder for the runtime configuration eg: `$HOME/.dapr/config.yaml` in Linux/MacOS and `%USERPROFILE%\.dapr\config.yaml` in Windows.
 

daprdocs/content/en/docs/concepts/faq.md

@@ -1,9 +1,8 @@
 ---
-title: "Frequently Asked Questions and Answers"
+title: "Frequently asked Questions and Answers"
 linkTitle: "FAQs"
-weight: 60
-description: >
-  Common questions we get asked about Dapr
+weight: 1000
+description: "Common questions asked about Dapr"
 ---
 
 ## Networking and service meshes

daprdocs/content/en/docs/concepts/middleware.md

@@ -1,13 +1,13 @@
 ---
-title: "Middleware Pipeline"
+title: "Middleware pipelines"
 linkTitle: "Middleware"
-weight: 300
+weight: 400
 description: "Custom processing pipelines of chained middleware components"
 ---
 
 Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. A request goes through all defined middleware components before it's routed to user code, and then goes through the defined middleware, in reverse order, before it's returned to the client, as shown in the following diagram.
 
-![Middleware](../../images/middleware.png)
+<img src="/images/middleware.png" width=800>
 
 ## Customize processing pipeline
 
@@ -56,8 +56,10 @@ func GetHandler(metadata Metadata) fasthttp.RequestHandler {
 }
 ```
 
-## Submitting middleware components
-Your middleware component can be contributed to the https://github.com/dapr/components-contrib repository, under the */middleware* folder. Then submit another pull request against the https://github.com/dapr/dapr repository to register the new middleware type. You'll need to modify the **Load()** method under https://github.com/dapr/dapr/blob/master/pkg/components/middleware/http/registry.go to register your middleware using the **Register** method.
+## Adding new middleware components
+Your middleware component can be contributed to the https://github.com/dapr/components-contrib repository, under the */middleware* folder. 
 
-## References
+Then submit another pull request against the https://github.com/dapr/dapr repository to register the new middleware type. You'll need to modify the **Load()** method under https://github.com/dapr/dapr/blob/master/pkg/components/middleware/http/registry.go to register your middleware using the **Register** method.
+
+## Next steps
 * [How-To: Configure API authorization with OAuth](../../howto/authorization-with-oauth/README.md)

daprdocs/content/en/docs/concepts/observability.md

@@ -0,0 +1,27 @@
+---
+title: "Observability"
+linkTitle: "Observability"
+weight: 500
+description: >
+  How to monitor applications through tracing, metrics, logs and health
+---
+
+Observability is a term from control theory. Observability means you can answer questions about what's happening on the inside of a system by observing the outside of the system, without having to ship new code to answer new questions. Observability is critical in production environments and services to debug, operate and monitor Dapr system services, components and user applications.
+
+The observability capabilities enable users to monitor the Dapr system services, their interaction with user applications and understand how these monitored services behave. The observability capabilities are divided into the following areas;
+
+* **[Distributed tracing](./traces.md)**: is used to profile and monitor Dapr system services and user apps. Distributed tracing helps pinpoint where failures occur and what causes poor performance. Distributed tracing is particularly well-suited to debugging and monitoring distributed software architectures, such as microservices.
+
+    You can use distributed tracing to help debug and optimize application code. Distributed tracing contains trace spans between the Dapr runtime, Dapr system services, and user apps across process, nodes, network, and security boundaries. It provides a detailed understanding of service invocations (call flows) and service dependencies.
+
+    Dapr uses [W3C tracing context for distributed tracing](./W3C-traces.md)
+
+    It is generally recommended to run Dapr in production with tracing.
+* **[Metrics](./metrics.md)**: are the series of measured values and counts that are collected and stored over time. Dapr metrics provide monitoring and understanding of the behavior of Dapr system services and user apps. For example, the service metrics between Dapr sidecars and user apps show call latency, traffic failures, error rates of requests etc. Dapr system services metrics show side car injection failures, health of the system services including CPU usage, number of actor placement made etc.  
+
+* **[Logs](./logs.md)**: are records of events that occur and can be used to determine failures or another status. Logs events contain warning, error, info, and debug messages produced by Dapr system services. Each log event includes metadata such as message type, hostname, component name, App ID, ip address, etc.
+
+* **[Health](./health.md)**: Dapr provides a way for a hosting platform to determine it's health using an HTTP endpoint. With this endpoint, the Dapr process, or sidecar, can be probed to determine its readiness and liveness and action taken accordingly.
+
+## Open Telemetry
+Dapr integrates with [OpenTelemetry](https://opentelemetry.io/) for tracing, metrics and logs. With OpenTelemetry, you can configure various exporters for tracing and metrics based on your environment, whether it is running in the cloud or on-premises.

daprdocs/content/en/docs/concepts/overview.md

@@ -1,7 +1,7 @@
 ---
-title: "Dapr Overview"
+title: "Overview"
 linkTitle: "Overview"
-weight: 10
+weight: 100
 description: >
   Introduction to the Distributed Application Runtime
 ---
@@ -22,7 +22,7 @@ Using Dapr you can easily build microservice applications using any language, an
 
 ## Microservice building blocks for cloud and edge
 
-<img src="/images/building_blocks.png" width=800>
+<img src="/images/building_blocks.png" width=1000>
 
 There are many considerations when architecting microservices applications. Dapr provides best practices for common capabilities when building microservice applications that developers can use in a standard way and deploy to any environment. It does this by providing distributed system building blocks.
 
@@ -49,13 +49,13 @@ Dapr can be hosted in multiple environments, including self hosted for local dev
 
 In self hosted mode Dapr runs as a separate side-car process which your service code can call via HTTP or gRPC. In self hosted mode, you can  also deploy Dapr onto a set of VMs.
 
-<img src="/images/overview-sidecar.png" width=600>
+<img src="/images/overview-sidecar.png" width=1000>
 
 ### Kubernetes hosted
 
 In container hosting environments such as Kubernetes, Dapr runs as a side-car container with the application container in the same pod.
 
-<img src="/images/overview-sidecar-kubernetes.png" width=600>
+<img src="/images/overview-sidecar-kubernetes.png" width=1000>
 
 ## Developer language SDKs and frameworks
 
@@ -68,6 +68,7 @@ To make using Dapr more natural for different languages, it also includes langua
 - **[Java SDK](https://github.com/dapr/java-sdk)**
 - **[Javascript SDK](https://github.com/dapr/js-sdk)**
 - **[Python SDK](https://github.com/dapr/python-sdk)**
+- **[RUST SDK](https://github.com/dapr/rust-sdk)**
 - **[.NET SDK](https://github.com/dapr/dotnet-sdk)**
 
 > Note: Dapr is language agnostic and provides a [RESTful HTTP API](../reference/api/README.md) in addition to the protobuf clients.

daprdocs/content/en/docs/concepts/security.md

@@ -1,26 +1,13 @@
 ---
-title: "Dapr Security"
+title: "Security"
 linkTitle: "Security"
-weight: 30
+weight: 600
 description: >
-  How Dapr is designed with security in mind for your enterprise deployments.
+  How Dapr is designed with security in mind
 ---
 
-# Security
-
 This article addresses multiple security considerations when using Dapr in a distributed application including:
 
-- [Sidecar-to-App Communication](#sidecar-to-app-communication)
-- [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication)
-- [Sidecar-to-system-services-communication](#sidecar-to-system-services-communication)
-- [Component namespace scopes and secrets](#component-namespace-scopes-and-secrets)
-- [Network Security](#network-security)
-- [Bindings Security](#bindings-security)
-- [State Store Security](#state-store-security)
-- [Management Security](#management-security)
-- [Threat Model](#threat-model)
-- [Security Audit June 2020](#security-audit-june-2020)
-
 Several of the areas above are addressed through encryption of data in transit. One of the security mechanisms that Dapr employs for encrypting data in transit is [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. mTLS offers a few key features for network traffic inside your application:
 
 - Two way authentication - the client proving its identify to the server, and vice-versa
@@ -30,11 +17,11 @@ Mutual TLS is useful in almost all scenarios, but especially so for systems subj
 
 Dapr enables mTLS and all the features described in this document in your application with little to no extra code or complex configuration inside your production systems
 
-## Sidecar-to-App communication
+## Sidecar-to-app communication
 
 The Dapr sidecar runs close to the application through **localhost**, and is recommended to run under the same network boundary as the app. While many cloud-native systems today consider the pod level (on Kubernetes, for example) as a trusted security boundary, Dapr provides user with API level authentication using tokens. This feature guarantees that even on localhost, only an authenticated caller may call into Dapr.
 
-## Sidecar-to-Sidecar communication
+## Sidecar-to-sidecar communication
 
 Dapr includes an "on by default", automatic mutual TLS that provides in-transit encryption for traffic between Dapr sidecars.
 To achieve this, Dapr leverages a system service named `Sentry` which acts as a Certificate Authority (CA) and signs workload (app) certificate requests originating from the Dapr sidecar.
@@ -59,12 +46,12 @@ This can be done for both Kubernetes and self hosted modes. Details for how to d
 ### mTLS self hosted
 The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored in a file
 
-![mTLS self hosted](../../images/security-mTLS-sentry-selfhosted.png)
+<img src="/images/security-mTLS-sentry-selfhosted.png" width=1000>
 
 ### mTLS in Kubernetes
 The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored as a Kubernetes secret
 
-![mTLS Kubernetes](../../images/security-mTLS-sentry-kubernetes.png)
+<img src="/images/security-mTLS-sentry-kubernetes.png" width=1000>
 
 ## Sidecar to system services communication
 
@@ -81,7 +68,7 @@ When the Dapr sidecar initializes, it authenticates with the system pods using t
 ### mTLS to system services in Kubernetes
 The diagram below shows secure communication between the Dapr sidecar and the Dapr Sentry (Certificate Authority), Placement (actor placement) and the Kubernetes Operator system services
 
-![mTLS System Services on Kubernetes](../../images/security-mTLS-dapr-system-services.png)
+<img src="/images/security-mTLS-dapr-system-services.png" width=1000>
 
 ## Component namespace scopes and secrets
 
@@ -118,7 +105,7 @@ When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Dire
 ## Threat Model
 Threat modeling is a process by which potential threats, such as structural vulnerabilities or the absence of appropriate safeguards, can be identified, enumerated, and mitigations can be prioritized. The Dapr threat model is below.
 
-![Threat Model](../../images/threat_model.png)
+<img src="/images/security-threat-model.png" alt="Dapr threat model" width=1000>
 
 ## Security Audit June 2020
 
@@ -137,7 +124,7 @@ The test focused on the following:
 * DoS attacks
 * Penetration testing
 
-The full report can be found [here](./audits/DAP-01-report.pdf).
+The full report can be found [here](/docs/Dapr-july-2020-security-audit-report.pdf).
 
 Two issues, one critical and one high, were fixed during the test.
 As of July 21st 2020, Dapr has 0 criticals, 2 highs, 2 mediums, 1 low, 1 info.

daprdocs/content/en/docs/developing-applications/building-blocks/_index.md

@@ -5,22 +5,3 @@ weight: 30
 description: "HTTP or gRPC APIs that can be called from user code and uses one or more Dapr components."
 ---
 
-A [building block](/docs/concepts/architecture/building-blocks) is as an HTTP or gRPC API that can be called from user code and uses one or more Dapr components. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
-
-The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks' capability.
-
-<img src="/images/concepts-building-blocks.png" width=250>
-  
-The following are the building blocks provided by Dapr:
-
-<img src="/images/building_blocks.png" width=1000>
-
-| Building Block | Endpoint | Description |
-|----------------|----------|-------------|
-| [**Service-to-Service Invocation**](./service-invocation) | `/v1.0/invoke` | Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
-| [**State Management**](./state-management) | `/v1.0/state` | Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence.
-| [**Publish and Subscribe**](./publish-subscribe-messaging) | `/v1.0/publish` `/v1.0/subscribe`|  Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
-| [**Resource Bindings**](./bindings)| `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the  Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
-| [**Actors**](./actors) | `/v1.0/actors` |  An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See * [Actor Overview](./actors#understanding-actors)
-| [**Observability**](./observability) | `N/A` |  Dapr system components and runtime emit metrics, logs, and traces to debug, operate and monitor Dapr system services, components and user applications.
-| [**Secrets**](./secrets) | `/v1.0/secrets` | Dapr offers a secrets building block API and integrates with secret stores such as Azure Key Vault and Kubernetes to store the secrets. Service code can call the secrets API to retrieve secrets out of the Dapr supported secret stores.

daprdocs/content/en/docs/developing-applications/building-blocks/observability/_index.md

@@ -6,27 +6,6 @@ description: >
   How to monitor your application with Dapr Observability
 ---
 
-# Observability
-
-Observability is a term from control theory. Observability means you can answer questions about what's happening on the inside of a system by observing the outside of the system, without having to ship new code to answer new questions. Observability is critical in production environments and services to debug, operate and monitor Dapr system services, components and user applications.
-
-The observability capabilities enable users to monitor the Dapr system services, their interaction with user applications and understand how these monitored services behave. The observability capabilities are divided into the following areas;
-
-* **[Metrics](./metrics.md)**: are the series of measured values and counts that are collected and stored over time. Dapr metrics provide monitoring and understanding of the behavior of Dapr system services and user apps. For example, the service metrics between Dapr sidecars and user apps show call latency, traffic failures, error rates of requests etc. Dapr system services metrics show side car injection failures, health of the system services including CPU usage, number of actor placement made etc.  
-* **[Logs](./logs.md)**: are records of events that occur and can be used to determine failures or another status. Logs events contain warning, error, info, and debug messages produced by Dapr system services. Each log event includes metadata such as message type, hostname, component name, App ID, ip address, etc.
-* **[Distributed tracing](./traces.md)**: is used to profile and monitor Dapr system services and user apps. Distributed tracing helps pinpoint where failures occur and what causes poor performance. Distributed tracing is particularly well-suited to debugging and monitoring distributed software architectures, such as microservices.
-
-    You can use distributed tracing to help debug and optimize application code. Distributed tracing contains trace spans between the Dapr runtime, Dapr system services, and user apps across process, nodes, network, and security boundaries. It provides a detailed understanding of service invocations (call flows) and service dependencies.
-
-    Dapr uses [W3C tracing context for distributed tracing](./W3C-traces.md)
-
-    It is generally recommended to run Dapr in production with tracing.
-
-* **[Health](./health.md)**: Dapr provides a way for a hosting platform to determine it's health using an HTTP endpoint. With this endpoint, the Dapr process, or sidecar, can be probed to determine its readiness and liveness and action taken accordingly.
-
-## Open Telemetry
-Dapr integrates with OpenTelemetry for metrics, logs and tracing. With OpenTelemetry, you can configure various exporters for tracing and metrics based on your environment, whether it is running in the cloud or on-premises.
-
 ## Monitoring tools
 
 The observability tools listed below are ones that have been tested to work with Dapr.

daprdocs/content/en/docs/developing-applications/building-blocks/service-invocation/howto-invoke-discover-services.md

@@ -2,7 +2,7 @@
 title: "Invoke & Discover Services"
 linkTitle: "How-To: Invoke & Discover Services"
 description: "This guide will walk you through configuring and invoking services using dapr"
-weight: 100
+weight: 200
 ---
 
 # Invoke remote services

daprdocs/content/en/docs/developing-applications/building-blocks/service-invocation/service-invocation-overview.md

@@ -0,0 +1,109 @@
+---
+title: "Service invocation"
+linkTitle: "Overview"
+description: "An overview of the features and capabilities of the service invocation building block"
+weight: 100
+---
+
+Using service invocation, your application can discover and reliably and securely communicate with other applications using the standard protocols of [gRPC](https://grpc.io) or [HTTP](https://www.w3.org/Protocols/). 
+
+## Overview
+In many environments with multiple services that need to communicate with each other, developers often ask themselves the following questions:
+
+* How do I discover and invoke methods on different services?
+* How do I call other services securely?
+* How do I handle retries and transient errors?
+* How do I use distributed tracing to see a call graph to diagnose issues in production?
+
+Dapr allows you to overcome these challenges by providing an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing, metrics, error handling and more.
+
+Dapr uses a sidecar, decentralized architecture. To invoke an application using Dapr, you use the `invoke` API on any Dapr instance. The sidecar programming model encourages each applications to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another.
+
+The diagram below is an overview of how Dapr's service invocation works.
+
+![Service Invocation Diagram](/images/service-invocation.png)
+
+1. Service A makes an http/gRPC call meant for Service B.  The call goes to the local Dapr sidecar.  
+2. Dapr discovers Service B's location using the [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) installed for the given hosting platform.
+3. Dapr forwards the message to Service B's Dapr sidecar 
+    * Note: All calls between Dapr sidecars go over gRPC for performance. Only calls between services and Dapr sidecars are either HTTP or gRPC
+4. Service B's Dapr sidecar forwards the request to the specified endpoint (or method) on Service B.  Service B then runs its business logic code.
+5. Service B sends a response to Service A.  The response goes to Service B's sidecar.
+6. Dapr forwards the response to Service A's Dapr sidecar.
+7. Service A receives the response.
+
+### Example
+As an example for the above call sequence, suppose you have the applications as described in the [hello world sample](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md), where a python app invokes a node.js app.
+
+In such a scenario, the python app would be "Service A" above, and the Node.js app would be "Service B".
+
+The diagram below shows sequence 1-7 again on a local machine showing the API call:
+
+![Service Invocation Diagram](../../images/service-invocation-example.png)
+
+1. Suppose the Node.js app has a Dapr app ID of `nodeapp`, as in the sample.  The python app invokes the Node.js app's `neworder` method by posting `http://localhost:3500/v1.0/invoke/nodeapp/method/neworder`, which first goes to the python app's local Dapr sidecar.
+2. Dapr discovers the Node.js app's location using multicast DNS component which runs on your local machine.
+3. Dapr forwards the request to the Node.js app's sidecar.
+4. The Node.js app's sidecar forwards the request to the Node.js app.  The Node.js app performs its business logic, which, as described in the sample, is to log the incoming message and then persist the order ID into Redis (not shown in the diagram above).
+
+    Steps 5-7 are the same as above.
+
+## Features
+Service invocation provides several features to make it easy for you to call methods on remote applications.
+
+- [Namespaces scoping](#namespaces-scoping)
+- [Retries](#Retries)
+- [Service-to-service security](#service-to-service-security)
+- [Service access security](#service-access-security)
+- [Observability: Tracing, logging and metrics](#observability)
+- [Pluggable service discovery](#pluggable-service-discovery)
+
+
+### Namespaces scoping
+Service invocation supports calls across namespaces. On all supported hosting platforms, Dapr app IDs conform to a valid FQDN format that includes the target namespace. 
+
+For example, the following string contains the app ID `nodeapp` in addition to the namespace the app runs in `production`.
+
+```
+localhost:3500/v1.0/invoke/nodeapp.production/method/neworder
+```
+
+This is especially useful in cross namespace calls in a Kubernetes cluster. Watch this [video](https://youtu.be/LYYV_jouEuA?t=495) for a demo on how to use namespaces with service invocation.
+
+### Retries
+Service invocation performs automatic retries with backoff time periods in the event of call failures and transient errors.
+Errors that cause retries are:
+
+* Network errors including endpoint unavailability and refused connections
+* Authentication errors due to a renewing certificate on the calling/callee Dapr sidecars
+
+Per call retries are performed with a backoff interval of 1 second up to a threshold of 3 times.
+Connection establishment via gRPC to the target sidecar has a timeout of 5 seconds. 
+
+### Service-to-service security
+All calls between Dapr applications can be made secure with mutual (mTLS) authentication on hosted platforms, including automatic certificate rollover, via the Dapr Sentry service. The diagram below shows this for self hosted applications.
+
+For more information read the [service-to-service security](../security#mtls-self-hosted) article.
+
+![Self Hosted service to service security](../../images/security-mTLS-sentry-selfhosted.png)
+
+### Service access security
+Applications can control which other applications are allowed to call them and what they are authorized to do via access policies. This enables you to restrict sensitive applications, that say have personnel information, from being accessed by unauthorized applications, and combined with service-to-service secure communication, provides for soft multi-tenancy deployments.
+
+For more information read the [access control allow lists for service invocation](../configuration#access-control-allow-lists-for-service-invocation) article.
+
+### Observability
+By default, all calls between applications are traced and metrics are gathered to provide insights and diagnostics for applications, which is especially important in production scenarios.  
+
+For more information read the [observability](../concepts/observability) article.
+
+### Pluggable service discovery
+Dapr can run on any [hosting platform](../concepts/hosting). For the supported hosting platforms this means they have a [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) developed for them that enables service discovery. For example, the Kubernetes name resolution component uses the Kubernetes DNS service to resolve the location of other applications running in the cluster.
+
+## Next steps
+
+* Follow these guide on
+    * [How-to: Get started with HTTP service invocation](../../howto/invoke-and-discover-services)
+    * [How-to: Get started with Dapr and gRPC](../../howto/create-grpc-app)
+* Try out the [hello world sample](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) which shows how to use HTTP service invocation or visit the samples in each of the [Dapr SDKs](https://github.com/dapr/docs#further-documentation)
+* Read the [service invocation API specification](../../reference/api/service_invocation_api.md)