update async messaging sequences

Author: jyecusch

docs/architecture/apis.mdx

@@ -95,8 +95,8 @@ sequenceDiagram
   participant Worker as App Worker(s)
   participant SDK as Nitric SDK
   participant Nitric as Nitric CLI
-  participant Provider as Nitric Provider
-  participant IAC as IaC
+  participant Provider as Nitric Provider <br> (plugin)
+  participant IAC as IaC <br> (e.g. Terraform)
 
   Worker->>SDK: Register API(s)
   SDK->>Nitric: Register API(s)
@@ -122,9 +122,9 @@ Here is the sequence of events that occur at runtime when a client makes an HTTP
 ```mermaid
 sequenceDiagram
   participant Client as Client
-  participant APIGateway as API Gateway
+  participant APIGateway as API Gateway <br> (e.g. AWS API Gateway)
   participant Auth as Auth Provider
-  participant Nitric as Nitric Runtime
+  participant Nitric as Nitric Runtime <br> (plugin)
   participant SDK as Nitric SDK
   participant Worker as App Worker
 

docs/architecture/buckets.mdx

@@ -94,8 +94,8 @@ sequenceDiagram
     participant Worker as App Worker(s)
     participant SDK as Nitric SDK
     participant Nitric as Nitric CLI
-    participant Provider as Nitric Provider
-    participant IAC as IaC
+    participant Provider as Nitric Provider <br> (plugin)
+    participant IAC as IaC <br> (e.g. Terraform)
 
     Worker->>SDK: Register Bucket
     Worker->>SDK: Register Access Requirements
@@ -125,10 +125,10 @@ Below is a sequence diagram showing the runtime flow of a storage operation in a
 sequenceDiagram
     participant Client as App Code
     participant SDK as Nitric SDK
-    participant Nitric as Nitric Runtime
-    participant CloudAPI as Cloud Storage (e.g. S3)
+    participant Nitric as Nitric Runtime <br> (plugin)
+    participant CloudAPI as Cloud Storage <br> (e.g. AWS S3)
 
-    Client->>SDK: Read
+    Client->>SDK: Read()
     SDK->>Nitric: Forward Request
     Nitric->>Nitric: Convert Request
     Nitric->>CloudAPI: Storage API Request

docs/architecture/keyvalue.mdx

@@ -79,8 +79,8 @@ sequenceDiagram
     participant Worker as App Worker(s)
     participant SDK as Nitric SDK
     participant Nitric as Nitric CLI
-    participant Provider as Nitric Provider
-    participant IAC as IaC
+    participant Provider as Nitric Provider <br> (plugin)
+    participant IAC as IaC <br> (e.g. Terraform)
 
     Worker->>SDK: Register Key/Value Store
     Worker->>SDK: Register Access Requirements
@@ -100,8 +100,8 @@ Below is a sequence diagram showing the runtime flow of a key/value store operat
 sequenceDiagram
     participant Client as App Code
     participant SDK as Nitric SDK
-    participant Nitric as Nitric Runtime
-    participant CloudAPI as Document DB
+    participant Nitric as Nitric Runtime <br> (plugin)
+    participant CloudAPI as Document DB <br> (e.g. AWS DynamoDB)
 
     Client->>SDK: Get(key)
     SDK->>Nitric: Forward Request

docs/architecture/queues.mdx

@@ -67,26 +67,43 @@ classDef edgeLabel line-height:2;
 
 ## 2. Sequence
 
+### Build Sequence
+
+Below is a sequence diagram showing the sequence of events when a developer registers a Queue with Nitric. This is the process that occurs when using the `nitric up` command.
+
+```mermaid
+sequenceDiagram
+    participant Worker as App Worker(s)
+    participant SDK as Nitric SDK
+    participant Nitric as Nitric CLI
+    participant Provider as Nitric Provider
+    participant IAC as IaC
+
+    Worker->>SDK: Register Queue
+    Worker->>SDK: Register Access Requirements
+    SDK->>Nitric: Register Queue
+    SDK->>Nitric: Register Access Requirements
+
+    Nitric->>Provider: Forward Nitric Spec
+    Provider->>IAC: Provision Queue
+    Provider->>IAC: Provision IAM
+```
+
+### Runtime Sequence
+
+Below is the runtime flow when performing operations on a Queue using Nitric, such as enqueueing or dequeueing messages. The example shows an Enqueue operation, which sends a message to the queue.
+
 ```mermaid
 sequenceDiagram
-    participant Client as Client
-    participant NitricSDK as Nitric SDK
-    participant NitricRuntime as Nitric Runtime
-    participant QueueService as Cloud Queue Service (e.g., AWS SQS, GCP Pub/Sub)
-
-    Client->>NitricSDK: Send or receive message from queue
-    NitricSDK->>NitricRuntime: Forward queue API call
-    NitricRuntime->>QueueService: Perform queue operation (e.g., enqueue, dequeue)
-
-    alt Successful Operation
-        QueueService-->>NitricRuntime: Return result (e.g., message or success status)
-        NitricRuntime-->>NitricSDK: Return result
-        NitricSDK-->>Client: Return result to client
-    else Failure
-        QueueService-->>NitricRuntime: Return error
-        NitricRuntime-->>NitricSDK: Forward error
-        NitricSDK-->>Client: Return error response
-    end
+    participant Client as App Code
+    participant SDK as Nitric SDK
+    participant Nitric as Nitric Runtime <br> (plugin)
+    participant CloudAPI as Document DB <br> (e.g. AWS SQS)
+
+    Client->>SDK: Enqueue(message)
+    SDK->>Nitric: Forward Request
+    Nitric->>Nitric: Convert Request
+    Nitric->>CloudAPI: Queue API Request
 ```
 
 ## 3. Component

docs/architecture/topics.mdx

@@ -82,28 +82,59 @@ classDef edgeLabel line-height:2;
 
 ## 2. Sequence
 
+### Build Sequence
+
+Below is a sequence diagram showing the sequence of events when a developer registers a Topic with Nitric and optionally registers Subscribers. This is the process that occurs when using the `nitric up` command.
+
+```mermaid
+sequenceDiagram
+    participant Worker as App Worker(s)
+    participant SDK as Nitric SDK
+    participant Nitric as Nitric CLI
+    participant Provider as Nitric Provider <br> (plugin)
+    participant IAC as IaC <br> (e.g. Terraform)
+
+    Worker->>SDK: Register Queue
+    Worker->>SDK: Register Access Requirements
+    SDK->>Nitric: Register Queue
+    SDK->>Nitric: Register Access Requirements
+
+    opt Subscribers
+      Worker->>SDK: Register Subscriber Callback
+      SDK->>Nitric: Register Subscriber
+    end
+
+    Nitric->>Provider: Forward Nitric Spec
+    Provider->>IAC: Provision Queue
+    Provider->>IAC: Provision IAM
+
+    opt Notifications
+      Provider->>IAC: Provision Event Rule(s)
+      Provider->>IAC: Provision IAM
+    end
+```
+
+### Runtime Sequence
+
+Below is the runtime flow when performing operations on a Topic using Nitric, such as publishing or subscribing to messages. The example shows both publish and subscribe operations, which send or receive messages to/from the topic.
+
 ```mermaid
 sequenceDiagram
-    participant Client as Client
-    participant NitricSDK as Nitric SDK
-    participant NitricRuntime as Nitric Runtime
-    participant TopicService as Cloud Topic Service (e.g., AWS SNS, GCP Pub/Sub)
-    participant Subscriber as Subscriber (e.g., Queue, Function)
-
-    Client->>NitricSDK: Publish message to topic
-    NitricSDK->>NitricRuntime: Forward topic API call
-    NitricRuntime->>TopicService: Publish message to topic
-
-    alt Successful Publish
-        TopicService-->>NitricRuntime: Confirm message delivery
-        NitricRuntime-->>NitricSDK: Return success confirmation
-        NitricSDK-->>Client: Return success to client
-        TopicService->>Subscriber: Distribute message to subscribers
-        Subscriber-->>TopicService: Acknowledge receipt of message
-    else Publish Failure
-        TopicService-->>NitricRuntime: Return error
-        NitricRuntime-->>NitricSDK: Forward error
-        NitricSDK-->>Client: Return error response
+    participant Client as App Code
+    participant SDK as Nitric SDK
+    participant Nitric as Nitric Runtime <br> (plugin)
+    participant CloudAPI as Message Broker <br> (e.g. AWS SNS)
+
+    alt Publisher
+        Client->>SDK: Publish(message)
+        SDK->>Nitric: Forward Request
+        Nitric->>Nitric: Convert Request
+        Nitric->>CloudAPI: Topic API Request
+    else Subscriber
+        CloudAPI->>Nitric: Message
+        Nitric->>Nitric: Convert Message
+        Nitric->>SDK: Forward Message
+        SDK->>Client: Subscription Callback
     end
 ```