Merge branch '14-mq-topic-structure-with-operator-appointed-name' into 'dev'

Resolve "MQ Topic Structure with operator appointed name"

Closes #14

See merge request !17

README.md

@@ -11,6 +11,63 @@ Each message below will be wrapped in a `payload` field and will have a `header`
 * `acknowledgement`: level of acknowledgment where an acknowledgement is sent when a message is i. received, ii. sent to the next destination (e.g. platform in the water).
 * `planning_configuration`: sent from the GUI to initialise the AI model (autonomy engine).
 
+## Topics 
+
+Messages are routed using either a publish/subscribe or broadcast mechanism. 
+
+For published messages, the message is published for a given a topic. 
+
+Clients create a subscription (stored in their config) to a topic pattern which may include wildcards. 
+
+It's important to note that the client config documents the subscription. To change a client 
+subscription it must be updated with the backbone.
+
+Published messages are delivered to all clients where 
+the message topic matches the client's subscription 
+topic pattern.
+
+Broadcast messages are delivered to all clients regardless of their subscription. 
+
+### Field
+
+The topic should be set in the `message.header.destination` for published messages. 
+The `destination` field should be set to `broadcast` for any messages sent using broadcast. 
+
+Because the `destination` field is a topic it defines what the message relates to - not 
+who the intended recipient is. 
+
+This means that the clients are not typically represented in the topics. A client publishes a message about a platform and subscribers interested in that project, platform or message type will receive that message.
+
+### Structure
+
+`<prefix>.<operator>.<platform_type>.<platform_identifier>.<to_platform|from_platform>.<message_type>`
+
+e.g
+* `soar.noc.autosub.ah1.from_platform.platform_status`
+* `soar.planet-ocean.ecosub.eco1.to_platform.mission_plan`
+* `soar.hydrosurv.reav.reav1.to_platform.mission_plan`
+
+### Terms
+
+* `prefix` - an agreed hard-coded/config setting prefix shared by all adapters and client subscriptions eg soar 
+* `operator` - human readable organisation name for the platform operator one of [noc|planet-ocean|hydrosurv] 
+* `platform_type` - one of [autosub|ecosub|reav?]
+* `platform_identifier` - human readable identifier for the platform eg ah1, eco1, reav1 
+* `to_platform|from_platform` - eg ..to_platform.mission_plan, ..from_platform.platform_status
+missions are sent `to_platform` to be executed and status updates are received `from_platform` containing 
+information about its position and health status
+* `message_type` - one of `[acknowledgement|mission_plan|observation|planning_configuration|platform_status...]`
+
+### Subscriptions
+
+Subscriptions may contain multiword wildcards (#) or single word wildcards (*)
+eg
+* `soar.#` - everything 
+* `soar.planet-ocean.#` - anything relating to the planet-ocean operator
+* `soar.*.*.*.from_platform.*` - all messages inbound from platforms (autonomy engine)
+* `soar.*.*.*.to_platform.*` - all messages outbound to platforms (hermes)
+* `soar.*.slocum.#` - all messages relating to a slocum platform type
+
 ## Run Docs
 Run the command below and go to `http://127.0.0.1:5000`
 ```