update

docs/architecture.md

@@ -12,10 +12,16 @@ The system uses **handler functions** to abstract file server operations, allowi
 
 ```julia
 # Upload handler - uploads data to file server and returns URL
+# The handler is passed to smartsend as fileserverUploadHandler parameter
+# It receives: (fileserver_url::String, dataname::String, data::Vector{UInt8})
+# Returns: Dict{String, Any} with keys: "status", "uploadid", "fileid", "url"
 fileserverUploadHandler(fileserver_url::String, dataname::String, data::Vector{UInt8})::Dict{String, Any}
 
-# Download handler - fetches data from file server URL
-fileserverDownloadHandler(fileserver_url::String, url::String, max_retries::Int, base_delay::Int, max_delay::Int)::Vector{UInt8}
+# Download handler - fetches data from file server URL with exponential backoff
+# The handler is passed to smartreceive as fileserverDownloadHandler parameter
+# It receives: (url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)
+# Returns: Vector{UInt8} (the downloaded data)
+fileserverDownloadHandler(url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)::Vector{UInt8}
 ```
 
 This design allows the system to support multiple file server backends without changing the core messaging logic.
@@ -154,8 +160,7 @@ end
   "brokerURL": "nats://localhost:4222",
   
   "metadata": {
-    "content_type": "application/octet-stream",
-    "content_length": 123456
+    
   },
   
   "payloads": [
@@ -168,7 +173,7 @@ end
       "size": 15433,
       "data": "base64-encoded-string",
       "metadata": {
-        "checksum": "sha256_hash"
+
       }
     },
     {
@@ -180,7 +185,7 @@ end
       "size": 524288,
       "data": "http://localhost:8080/file/UPLOAD_ID/FILE_ID/data.arrow",
       "metadata": {
-        "checksum": "sha256_hash"
+
       }
     }
   ]
@@ -321,19 +326,19 @@ function smartsend(
 
 ```julia
 function smartreceive(
-  msg::NATS.Message;
-  fileserverDownloadHandler::Function,
-  max_retries::Int = 5,
-  base_delay::Int = 100,
-  max_delay::Int = 5000
+    msg::NATS.Message,
+    fileserverDownloadHandler::Function=_fetch_with_backoff;
+    max_retries::Int = 5,
+    base_delay::Int = 100,
+    max_delay::Int = 5000
 )
-  # Parse envelope
-  # Iterate through all payloads
-  # For each payload: check transport type
-  #   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) tuples
+    # Parse envelope
+    # Iterate through all payloads
+    # For each payload: check transport type
+    #   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) tuples
 end
 ```
 
@@ -347,10 +352,12 @@ end
 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
+   - 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)` tuples
 
+**Note:** The `fileserverDownloadHandler` receives `(url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)` and returns `Vector{UInt8}`.
+
 ### JavaScript Implementation
 
 #### Dependencies
@@ -388,10 +395,10 @@ async function smartsend(subject, data, options = {})
 async function smartreceive(msg, options = {})
     // options object should include:
     // - fileserverDownloadHandler: function to fetch data from file server URL
-    // - fileserver_url: base URL of the file server
     // - max_retries: maximum retry attempts for fetching URL
     // - base_delay: initial delay for exponential backoff in ms
     // - max_delay: maximum delay for exponential backoff in ms
+    // - correlationId: optional correlation ID for tracing
 ```
 
 **Process Flow:**