docs: document topics and subscriptions

README.md

@@ -11,6 +11,61 @@ 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 to a topic pattern which may include wildcards. 
+
+Messages with a topic matching a client's subscription pattern are delivered to that client.
+
+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 desintation field should be set to `broadcast` for any messages sent using broadcast. 
+
+### Structure
+
+`<prefix>.<operator>.<platform_type>.<platform_identifier>.<send|receive>.<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
+
+The `header.destination` field contains the topic that messages will be published to.
+
+This is not the intended recipient of those messages.
+
+The autonomy engine/frontend/c2s are not represented in the topic.
+
+The topic describes what the message relates to.
+
+The client `subscription` will define which clients receive a message.
+
+* `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
+* `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`
 ```