update

docs/architecture.md

@@ -35,8 +35,24 @@ The system uses a **standardized list-of-tuples format** for all payload operati
 # Input format for smartsend (always a list of tuples with type info)
 [(dataname1, data1, type1), (dataname2, data2, type2), ...]
 
-# Output format for smartreceive (always returns a list of tuples)
-[(dataname1, data1, type1), (dataname2, data2, type2), ...]
+# Output format for smartreceive (returns envelope dictionary with payloads field)
+# Returns: Dict with envelope metadata and payloads field containing list of tuples
+# {
+#   "correlationId": "...",
+#   "msgId": "...",
+#   "timestamp": "...",
+#   "sendTo": "...",
+#   "msgPurpose": "...",
+#   "senderName": "...",
+#   "senderId": "...",
+#   "receiverName": "...",
+#   "receiverId": "...",
+#   "replyTo": "...",
+#   "replyToMsgId": "...",
+#   "brokerURL": "...",
+#   "metadata": {...},
+#   "payloads": [(dataname1, data1, type1), (dataname2, data2, type2), ...]
+# }
 ```
 
 **Supported Types:**
@@ -81,9 +97,10 @@ smartsend(
     nats_url="nats://localhost:4222"
 )
 
-# Receive always returns a list
-payloads = smartreceive(msg, fileserverDownloadHandler, max_retries, base_delay, max_delay)
-# payloads = [("dataname1", data1, type1), ("dataname2", data2, type2), ...]
+# Receive returns a dictionary envelope with all metadata and deserialized payloads
+envelope = smartreceive(msg, fileserverDownloadHandler, max_retries, base_delay, max_delay)
+# envelope["payloads"] = [("dataname1", data1, type1), ("dataname2", data2, type2), ...]
+# envelope["correlationId"], envelope["msgId"], etc.
 ```
 
 ## Architecture Diagram
@@ -338,23 +355,25 @@ function smartreceive(
     #   If direct: decode Base64 payload
     #   If link: fetch from URL with exponential backoff using fileserverDownloadHandler
     # Deserialize payload based on type
-    # Return list of (dataname, data, type) tuples
+    # Return envelope dictionary with all metadata and deserialized payloads
 end
 ```
 
 **Output Format:**
-- Always returns a list of tuples: `[(dataname1, data1, type1), (dataname2, data2, type2), ...]`
-- Even for single payloads: `[(dataname1, data1, type1)]`
+- Returns a dictionary (key-value map) containing all envelope fields:
+  - `correlationId`, `msgId`, `timestamp`, `sendTo`, `msgPurpose`, `senderName`, `senderId`, `receiverName`, `receiverId`, `replyTo`, `replyToMsgId`, `brokerURL`
+  - `metadata` - Message-level metadata dictionary
+  - `payloads` - List of dictionaries, each containing deserialized payload data
 
 **Process Flow:**
-1. Parse the JSON envelope to extract the `payloads` array
+1. Parse the JSON envelope to extract all fields
 2. Iterate through each payload in `payloads`
 3. For each payload:
    - Determine transport type (`direct` or `link`)
    - If `direct`: decode Base64 data from the message
    - If `link`: fetch data from URL using exponential backoff (via `fileserverDownloadHandler`)
    - Deserialize based on payload type (`dictionary`, `table`, `binary`, etc.)
-4. Return list of `(dataname, data, type)` tuples
+4. Return envelope dictionary with `payloads` field containing list of `(dataname, data, type)` tuples
 
 **Note:** The `fileserverDownloadHandler` receives `(url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)` and returns `Vector{UInt8}`.
 
@@ -401,15 +420,21 @@ async function smartreceive(msg, options = {})
     // - correlationId: optional correlation ID for tracing
 ```
 
+**Output Format:**
+- Returns a dictionary (key-value map) containing all envelope fields:
+  - `correlationId`, `msgId`, `timestamp`, `sendTo`, `msgPurpose`, `senderName`, `senderId`, `receiverName`, `receiverId`, `replyTo`, `replyToMsgId`, `brokerURL`
+  - `metadata` - Message-level metadata dictionary
+  - `payloads` - List of dictionaries, each containing deserialized payload data
+
 **Process Flow:**
-1. Parse the JSON envelope to extract the `payloads` array
+1. Parse the JSON envelope to extract all fields
 2. Iterate through each payload in `payloads`
 3. For each payload:
    - Determine transport type (`direct` or `link`)
    - If `direct`: decode Base64 data from the message
    - If `link`: fetch data from URL using exponential backoff
    - Deserialize based on payload type (`dictionary`, `table`, `binary`, etc.)
-4. Return list of `(dataname, data, type)` tuples
+4. Return envelope dictionary with `payloads` field containing list of `(dataname, data, type)` tuples
 
 ## Scenario Implementations