--- a/mod_web_push/README.markdown	Sat Jun 08 23:06:44 2019 +0200
+++ b/mod_web_push/README.markdown	Sun Jun 09 22:02:24 2019 +0200
@@ -14,7 +14,8 @@
 :::
 
 This is an implementation of the server bits of [XEP-XXXX: Web Push].
-It allows clients to register a "push server" which is notified about new
+
+It allows web clients to register a "push server" which is notified about new
 messages while the user is offline, disconnected or the session is hibernated
 by [mod_smacks].
 
@@ -22,6 +23,37 @@
 
 This module is heavily based on [mod_cloud_notify].
 
+Details
+=======
+
+[Push API](https://w3c.github.io/push-api/) is a specification by the W3C that
+is essentially the same principle as Mobile OS vendors' Push notification
+systems. It is implemented by most browsers vendors except Safari on iOS
+(mobile).
+
+For more information, see:
+- https://developer.mozilla.org/en-US/docs/Web/API/Push_API
+- https://developers.google.com/web/ilt/pwa/introduction-to-push-notifications
+
+Compared to [XEP-0357: Push Notifications], Web Push doesn't need an App
+Server.
+
+The general flow for subscription is:
+- XMPP server generate ECDH keypair, publishes public key
+- XMPP client generates an ECDH keypair
+- XMPP client fetches server public key
+- XMPP client subscribes to browser Push server using the Web Push API, and
+  gets back an HTTP endpoint
+- XMPP client enables Push notifications telling the server the HTTP endpoint,
+  and its public key
+
+The flow for notifications is as follow:
+- XMPP server receives an _important_[^1] message
+- XMPP server generates something something JWT + signature with ECDH key
+- XMPP server can optionally include payload encrypted for the client
+- XMPP server initiates HTTP POST request to the Push server
+- Push server sends notification to web browser
+
 Configuration
 =============
 
@@ -43,3 +75,5 @@
 =============
 
 Configured in-band by supporting clients.
+
+[^1]: As defined in mod_cloud_notify, or mod_csi_simple.