Document the updated hook-based mod_event_pusher logic

Also:
- Restructure the docs
  - Start with a simple introduction
  - Follow with configuration
  - Only then provide developer's info
- Update migration guide

Author: chrzaszcz

doc/migrations/6.4.0_6.5.0.md

@@ -32,6 +32,10 @@ Instead of always sending all notifications, it only enables the ones with a rel
 
 Make sure you have all the necessary sections present in the configuration file before upgrading.
 
+### Custom backends for `mod_event_pusher`
+
+If you have a custom backend implemented for `mod_event_pusher`, you need to update it to handle the `push_event` hook instead of implementing the `mod_event_pusher` behaviour (which no longer exists).
+
 ### Deprecation
 
 MSSQL backend is deprecated and will be removed in the next release.

doc/modules/mod_event_pusher.md

@@ -1,18 +1,10 @@
 ## Module Description
 
-This module is a generic interface for event-pushing backends.
-It defines a single callback, `push_event/2` that forwards the event to all registered backends.
-Each backend decides how and if to handle the event in its `push_event/2` implementation.
-
+This module is a generic interface for pushing **events** to the configured **backends**.
+The events include presence updates and incoming/outgoing messages.
 Currently supported backends include [http], [push], [rabbit] and [sns].
 Refer to their specific documentation to learn more about their functions and configuration options.
 
-### How it works
-
-The events are standardized as records that can be found in the `mod_event_pusher_events.hrl` file.
-Common events like user presence changes (offline and online), chat and groupchat messages (incoming
-and outgoing) are already handled in the `mod_event_pusher_hook_translator` module, which is a proxy between various hooks and the `push_event/2` handler.
-
 !!! Warning
     This module does not support [dynamic domains](../configuration/general.md#generalhost_types).
 
@@ -46,6 +38,36 @@ The `[modules.mod_event_pusher]` section itself is omitted - this is allowed in
 [modules.mod_event_pusher.rabbit]
 ```
 
+## How it works
+
+The events are standardized as records that can be found in the `mod_event_pusher_events.hrl` file.
+Common events like user presence changes (offline and online), chat and groupchat messages (incoming and outgoing) are handled in the `mod_event_pusher_hook_translator` module.
+Each event has a corresponding [hook](../developers-guide/Hooks-and-handlers.md), e.g. `user_send_message` is run when a user sends a message.
+`mod_event_pusher_hook_translator` has a handler function for each supported hook.
+
+Handling an event includes the following steps:
+
+1. The event hook is executed, and the corresponding handler function in `mod_event_pusher_hook_translator` is called.
+1. The handler function calls `mod_event_pusher:push_event(Acc, Event)`.
+1. `mod_event_pusher:push_event/2` runs another hook called `push_event`.
+1. All configured backend modules have handlers for the `push_event` hook, and all these handlers are called.
+
+### Custom event processing
+
+By implementing your own module handling the `push_event` hook, you can:
+
+- Push the events to a new service, such as a message queue or a database.
+- Filter the events by returning `{ok, ...}` to keep an event, or `{stop, ...}` to drop it.
+- Add a map with **metadata** to the events. The keys need to be atoms, and the values need to be atoms, binaries or numbers.
+
+There is an example [mod_event_pusher_filter.erl](https://github.com/esl/MongooseIM/blob/master/big_tests/tests/mod_event_pusher_filter.erl) module, demonstrating how to filter the events and append additional metadata.
+
+!!! Note
+    Execution order of handlers depends on their priorities. In particular, filtering events or adding metadata needs to happend before pushing notifications to external services. The example handler has the priority value of 10, while backends have the priority of 50.
+
+!!! Warning
+    Currently only the [rabbit](mod_event_pusher_rabbit.md#additional-metadata) backend supports adding metadata to the published notifications.
+
 [http]: ./mod_event_pusher_http.md
 [push]: ./mod_event_pusher_push.md
 [rabbit]: ./mod_event_pusher_rabbit.md

doc/modules/mod_event_pusher_rabbit.md

@@ -185,6 +185,10 @@ and for "received" events:
 }
 ```
 
+## Additional metadata
+
+If you decide to [customize the events](mod_event_pusher.md#event-customization) with additional metadata, the additional key-value pairs will be added directly to the JSON object. You can override existing properties, but it is counter-intuitive and thus not recommended.
+
 ## Metrics
 
 The module provides some metrics related to RabbitMQ connections and messages