update

docs/architecture.md

@@ -369,6 +369,25 @@ graph TD
 
 ## Implementation Details
 
+### API Consistency Across Languages
+
+**High-Level API (Consistent Across All Languages):**
+- `smartsend(subject, data, ...)` - Main publishing function
+- `smartreceive(msg, ...)` - Main receiving function
+- Message envelope structure (`msg_envelope_v1` / `MessageEnvelope`)
+- Payload structure (`msg_payload_v1` / `MessagePayload`)
+- Transport strategy (direct vs link based on size threshold)
+- Supported payload types: text, dictionary, table, image, audio, video, binary
+
+**Low-Level Native Functions (Language-Specific Conventions):**
+- Julia: `NATS.connect()`, `publish_message()`, function overloading
+- JavaScript: `nats.js` client, native async/await patterns
+- Python: `nats-python` client, native async/await patterns
+
+**Connection Reuse Pattern:**
+- **Julia:** Uses `NATS_connection` keyword parameter with function overloading
+- **JavaScript/Python:** Achieved by creating NATS client outside the function and reusing it in custom handlers
+
 ### Julia Implementation
 
 #### Dependencies
@@ -400,7 +419,7 @@ function smartsend(
 )
 ```
 
-**New Keyword Parameter:**
+**Keyword Parameter - NATS_connection:**
 - `NATS_connection::Union{NATS.Connection, Nothing} = nothing` - Pre-existing NATS connection. When provided, `smartsend` uses this connection instead of creating a new one, avoiding the overhead of connection establishment. This is useful for high-frequency publishing scenarios where connection reuse provides performance benefits.
 
 **Connection Handling Logic:**
@@ -498,7 +517,7 @@ function publish_message(conn::NATS.Connection, subject::String, message::String
 end
 ```
 
-**Use Case:** Use the connection-based overload when you already have an established NATS connection and want to publish multiple messages without the overhead of creating a new connection for each publish.
+**Use Case:** Use the connection-based overload when you already have an established NATS connection and want to publish multiple messages without the overhead of creating a new connection for each publish. This is a Julia-specific optimization that leverages function overloading.
 
 **Integration with smartsend:**
 ```julia
@@ -521,6 +540,10 @@ env, env_json_str = smartsend(
 # Uses: publish_message(broker_url, subject, env_json_str, cid)
 ```
 
+**API Consistency Note:**
+- **High-level API (smartsend, smartreceive):** Uses consistent naming across all three languages (Julia, JavaScript, Python/Micropython)
+- **Low-level native functions (NATS.connect(), publish_message()):** Follow the conventions of the specific language ecosystem and do not require cross-language consistency
+
 ### JavaScript Implementation
 
 #### Dependencies
@@ -551,8 +574,11 @@ async function smartsend(
 - `receiver_id` (String) - Message receiver ID (default: `""`)
 - `reply_to` (String) - Topic to reply to (default: `""`)
 - `reply_to_msg_id` (String) - Message ID this message is replying to (default: `""`)
+- `is_publish` (Boolean) - Whether to automatically publish the message to NATS (default: `true`)
 - `fileserver_upload_handler` (Function) - Custom upload handler function
 
+**Note:** JavaScript uses `is_publish` option (instead of `NATS_connection` keyword) to control automatic publishing behavior. Connection reuse can be achieved by creating a NATS client outside the function and reusing it in a custom `fileserver_upload_handler` or custom publish implementation.
+
 **Return Value:**
 - Returns a Promise that resolves to an object containing:
   - `env` - The envelope object containing all metadata and payloads
@@ -618,26 +644,40 @@ async function smartreceive(msg, options = {})
 #### smartsend Function
 
 ```python
-async def smartsend(
+def smartsend(
     subject: str,
     data: List[Tuple[str, Any, str]],  # List of (dataname, data, type) tuples
-    options: Dict = {}
-)
+    broker_url: str = DEFAULT_BROKER_URL,
+    fileserver_url: str = DEFAULT_FILESERVER_URL,
+    fileserver_upload_handler: Callable = plik_oneshot_upload,
+    size_threshold: int = DEFAULT_SIZE_THRESHOLD,
+    correlation_id: Union[str, None] = None,
+    msg_purpose: str = "chat",
+    sender_name: str = "NATSBridge",
+    receiver_name: str = "",
+    receiver_id: str = "",
+    reply_to: str = "",
+    reply_to_msg_id: str = "",
+    is_publish: bool = True
+) -> Tuple[MessageEnvelope, str]
 ```
 
 **Options:**
 - `broker_url` (str) - NATS server URL (default: `"nats://localhost:4222"`)
 - `fileserver_url` (str) - Base URL of the file server (default: `"http://localhost:8080"`)
 - `size_threshold` (int) - Threshold in bytes for transport selection (default: `1048576` = 1MB)
-- `correlation_id` (str) - Optional correlation ID for tracing
+- `correlation_id` (str) - Optional correlation ID for tracing (auto-generated if None)
 - `msg_purpose` (str) - Purpose of the message (default: `"chat"`)
 - `sender_name` (str) - Sender name (default: `"NATSBridge"`)
 - `receiver_name` (str) - Message receiver name (default: `""`)
 - `receiver_id` (str) - Message receiver ID (default: `""`)
 - `reply_to` (str) - Topic to reply to (default: `""`)
 - `reply_to_msg_id` (str) - Message ID this message is replying to (default: `""`)
+- `is_publish` (bool) - Whether to automatically publish the message to NATS (default: `True`)
 - `fileserver_upload_handler` (Callable) - Custom upload handler function
 
+**Note:** Python uses `is_publish` parameter (instead of `NATS_connection` keyword) to control automatic publishing behavior. Connection reuse can be achieved by creating a NATS client outside the function and reusing it in a custom `fileserver_upload_handler` or custom publish implementation.
+
 **Return Value:**
 - Returns a tuple `(env, env_json_str)` where:
   - `env` - The envelope dictionary containing all metadata and payloads