Improve Directory documentation

docs/features/directory-users.md

@@ -1,4 +1,16 @@
 # User Directory
+- [Description](#description)
+- [Overview](#overview)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+  - [Reverse Proxy](#reverse-proxy)
+  - [DNS Overwrite](#dns-overwrite)
+  - [Backends](#backends)
+    - [LDAP](#ldap)
+    - [SQL](#sql)
+    - [REST](#rest)
+
+## Description
 This feature allows you to search for existing and/or potential users that are already present in your Identity backend
 or that already share a room with you on the Homeserver.
 
@@ -11,24 +23,34 @@ With mxisd integration, you can:
 - Search for users which you are not in contact with yet. Super useful for corporations who want to give Matrix access
 internally, so users can just find themselves **prior** to having any common room(s)
 - Use any attribute of your backend to extend the search!
+- Include your homeserver search results to those found by mxisd (default behaviour, no configuration required)
+
+By integrating mxisd, you get the default behaviour with all the extras, ensuring your users will always find each other.
 
 ## Overview
 This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/user_directory/search` like so:
 ```
            +----------------------------------------------+
-client --> | Reverse proxy                                                                         Step 2
+Client --> | Reverse proxy                                                                         Step 2
-           |                                                Step 1  +-------------------------+
+           |                                              Step 1    +-------------------------+
            |   /_matrix/client/r0/user_directory/search ----------> |                         |  Search in   +---------+
            |                        /\                              | mxisd - Identity server | -----------> | Backend |
            |   /_matrix/*            \----------------------------- |                         |  all users   +---------+
            |        |            Step 4: Send back merged results   +-------------------------+
-           +--------|-------                                                     |
+           +        |                                                            |
                     |                                                          Step 3
                     |                                                            |
                     |    +------------+                                Search in known users
                     \--> | Homeserver | <----------------------------------------/
                          +------------+   /_matrix/client/r0/user_directory/search
 ```
+Steps:
+1. The intercepted request is directly sent to mxisd instead of the Homeserver.
+2. Enabled backends are queried for any math on the search value sent by the client.
+3. The Homeserver, from which the request was intercepted, is queried using the same request as the client.
+Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
+4. Results from backends and the Homeserver are merged together and sent back to the client, believing it was the HS
+which directly answered the request.
 
 ## Requirements
 - Reverse proxy setup, which you should already have in place if you use mxisd
@@ -38,19 +60,34 @@ client --> | Reverse proxy
   - REST
   
 ## Configuration
-### Reverse proxy
+### Reverse Proxy
 Apache2 configuration to put under the relevant virtual domain:
 ```
 ProxyPreserveHost on
 ProxyPass /_matrix/identity/ http://mxisdInternalIpAddress:8090/_matrix/identity/
 ProxyPass /_matrix/client/r0/user_directory/ http://mxisdInternalIpAddress:8090/_matrix/client/r0/user_directory/
 ProxyPass /_matrix/ http://HomeserverInternalIpAddress:8008/_matrix/
-
 ```
 `ProxyPreserveHost` or equivalent must be enabled to detect to which Homeserver mxisd should talk to when building
 results.
 
-### Backend
+### DNS Overwrite
+Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
+the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
+
+To do so, use the following configuration:
+```
+dns.overwrite.homeserver.client:
+  - name: 'example.org'
+    value: 'http://localhost:8008'
+```
+`name` must be the hostname of the URL that clients use when connecting to the Homeserver.  
+In case the hostname is the same as your Matrix domain, you can use `${matrix.domain}` to auto-populate the value using
+the `matrix.domain` configuration option and avoid duplicating it.
+
+`value` is the base intenral URL of the Homeserver, without any `/_matrix/..` or trailing `/`.
+
+### Backends
 #### LDAP
 Configuration structure has been altered so queries are automatically built from a global or specific filter and a list
 of attributes. To ensure Directory feature works, here how the LDAP configuration should look like:
@@ -129,18 +166,3 @@ For each query, `type` can be used to tell mxisd how to process the ID column:
 
 #### REST
 See the [dedicated document](../backends/rest.md)
-### DNS Overwrite
-Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
-the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
-
-To do so, use the following configuration:
-```
-dns.overwrite.homeserver.client:
-  - name: 'example.org'
-    value: 'http://localhost:8008'
-```
-`name` must be the hostname of the URL that clients use when connecting to the Homeserver.  
-In case the hostname is the same as your Matrix domain, you can use `${matrix.domain}` to auto-populate the value using
-the `matrix.domain` configuration option and avoid duplicating it.
-
-`value` is the base intenral URL of the Homeserver, without any `/_matrix/..` or trailing `/`.