guides/federation.md

@@ -80,6 +80,20 @@ In this code I have created a link to an external user, which I have then made t
 
 Similarly this service will manage saves for `Update`/`Delete` activities on a model, and `Add`/`Remove` activities for many-to-many relationships
 
+#### ActivityQueueService
+
+The activities themselves are sent via `ActivityQueueService`. You shouldn't need to use this class, but for contributors to DjangoLDP the class is described below:
+
+The `ActivityQueueService` is a singleton, and its job is to ensure that duplicate or redundant activities are rejected, and valid activity deliveries are attempted multiple times before handling failure. Note that currently failure is logged to the default djangoldp logger, and [in future there are plans to handle this automatically using a sentry server](https://git.startinblox.com/djangoldp-packages/djangoldp/issues/273)
+
+This is achieved via a process of **scheduling** activities. Activities are scheduled by calling `send_activity` as a json object, which saves the state of the activity in a `ScheduledActivity` object and passes it to a worker thread to handle. There is a short delay, configurable as seconds by `settings.DEFAULT_ACTIVITY_DELAY`, at which point the activity is analysed. If it's up-to-date and signifies a change worthy of notification, `do_post` is called to handle the sending of the request
+
+If the activity is successful, it is saved and the `ScheduledActivity` deleted, freeing the queue itself to take on new activities. If it is unsuccessful, `resend_activity` is used to reschedule the activity according to a [backoff factor](https://www.peterbe.com/plog/best-practice-with-retries-with-requests), and the sending is re-attempted. The back-off factor defaults to 1 but can be configured with `settings.DEFAULT_BACKOFF_FACTOR`. After a configurable number of reschedules (`settings.MAX_ACTIVITY_RESCHEDULES`), the activity is abandoned and saved in a failed state. It is assumed that the server recipient is unreachable and requires intervention
+
+If the server is restarted, unsent activities are re-scheduled without data loss, in `ActivityQueueService.start`, called on DjangoLDP start-up
+
+Whilst `ActivityQueueService` is used natively to handle backlinks, it can be used to send any JSON content through the queue
+
 ### Responding to Backlinks
 
 DjangoLDP defines an `InboxView` which is capable of receiving ActivityStreams format requests. Upon successfully parsing an activity, it returns `201 - Accepted` with the URL of the stored activity in the `Location` header of the response