smart_message 0.0.10 → 0.0.13

data/examples/redis/redis_transport_architecture.svg

@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="900" height="700" viewBox="0 0 900 700" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .bg { fill: transparent; }
+      .process { fill: #2a2a2a; stroke: #4a9eff; stroke-width: 2; rx: 8; }
+      .redis { fill: #3a1a1a; stroke: #ff4a4a; stroke-width: 3; rx: 12; }
+      .channel { fill: #1a2a3a; stroke: #4affff; stroke-width: 2; rx: 6; }
+      .device { fill: #1a3a1a; stroke: #4aff4a; stroke-width: 2; rx: 6; }
+      .arrow { stroke: #ffaa4a; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
+      .text { fill: #ffffff; font-family: 'Arial', sans-serif; font-size: 12px; }
+      .title { fill: #4a9eff; font-family: 'Arial', sans-serif; font-size: 18px; font-weight: bold; }
+      .subtitle { fill: #ffaa4a; font-family: 'Arial', sans-serif; font-size: 11px; }
+      .redis-text { fill: #ff4a4a; font-family: 'Arial', sans-serif; font-size: 14px; font-weight: bold; }
+      .channel-text { fill: #4affff; font-family: 'Arial', sans-serif; font-size: 10px; }
+    </style>
+    <marker id="arrowhead" markerWidth="8" markerHeight="6" 
+            refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#ffaa4a" />
+    </marker>
+  </defs>
+  
+  <!-- Background -->
+  <rect class="bg" width="900" height="700"/>
+  
+  <!-- Title -->
+  <text x="450" y="25" text-anchor="middle" class="title">SmartMessage Redis Transport Architecture</text>
+  <text x="450" y="45" text-anchor="middle" class="subtitle">Distributed Smart Home IoT System (01_smart_home_iot_demo.rb)</text>
+  
+  <!-- Redis Server (Central Hub) -->
+  <rect x="350" y="300" width="200" height="120" class="redis"/>
+  <text x="450" y="325" text-anchor="middle" class="redis-text">Redis Server</text>
+  <text x="450" y="345" text-anchor="middle" class="text">localhost:6379</text>
+  <text x="450" y="365" text-anchor="middle" class="subtitle">Pub/Sub Channels:</text>
+  <text x="450" y="385" text-anchor="middle" class="channel-text">SensorDataMessage</text>
+  <text x="450" y="400" text-anchor="middle" class="channel-text">DeviceCommandMessage</text>
+  <text x="450" y="415" text-anchor="middle" class="channel-text">SecurityAlertMessage</text>
+  
+  <!-- Process 1: Living Room Sensors -->
+  <rect x="50" y="80" width="160" height="120" class="process"/>
+  <text x="130" y="105" text-anchor="middle" class="title">Process 1</text>
+  <text x="130" y="125" text-anchor="middle" class="text">Living Room</text>
+  
+  <rect x="70" y="140" width="120" height="50" class="device"/>
+  <text x="130" y="160" text-anchor="middle" class="text">Temperature Sensor</text>
+  <text x="130" y="175" text-anchor="middle" class="subtitle">Publishes every 5s</text>
+  
+  <!-- Process 2: Security System -->
+  <rect x="50" y="480" width="160" height="120" class="process"/>
+  <text x="130" y="505" text-anchor="middle" class="title">Process 2</text>
+  <text x="130" y="525" text-anchor="middle" class="text">Security System</text>
+  
+  <rect x="70" y="540" width="120" height="50" class="device"/>
+  <text x="130" y="560" text-anchor="middle" class="text">Motion Detector</text>
+  <text x="130" y="575" text-anchor="middle" class="subtitle">Publishes alerts</text>
+  
+  <!-- Process 3: Smart Thermostat -->
+  <rect x="690" y="80" width="160" height="120" class="process"/>
+  <text x="770" y="105" text-anchor="middle" class="title">Process 3</text>
+  <text x="770" y="125" text-anchor="middle" class="text">Smart Thermostat</text>
+  
+  <rect x="710" y="140" width="120" height="50" class="device"/>
+  <text x="770" y="160" text-anchor="middle" class="text">HVAC Controller</text>
+  <text x="770" y="175" text-anchor="middle" class="subtitle">Subscribes &amp; Controls</text>
+  
+  <!-- Process 4: Dashboard -->
+  <rect x="690" y="480" width="160" height="120" class="process"/>
+  <text x="770" y="505" text-anchor="middle" class="title">Process 4</text>
+  <text x="770" y="525" text-anchor="middle" class="text">Home Dashboard</text>
+  
+  <rect x="710" y="540" width="120" height="50" class="device"/>
+  <text x="770" y="560" text-anchor="middle" class="text">Web Interface</text>
+  <text x="770" y="575" text-anchor="middle" class="subtitle">Displays all data</text>
+  
+  <!-- Process 5: Energy Monitor -->
+  <rect x="370" y="80" width="160" height="120" class="process"/>
+  <text x="450" y="105" text-anchor="middle" class="title">Process 5</text>
+  <text x="450" y="125" text-anchor="middle" class="text">Energy Monitor</text>
+  
+  <rect x="390" y="140" width="120" height="50" class="device"/>
+  <text x="450" y="160" text-anchor="middle" class="text">Power Meter</text>
+  <text x="450" y="175" text-anchor="middle" class="subtitle">Tracks usage</text>
+  
+  <!-- Message Flow Arrows -->
+  <!-- Publishers to Redis -->
+  <path d="M 210 140 L 350 330" class="arrow"/>
+  <path d="M 210 540 L 350 380" class="arrow"/>
+  <path d="M 450 200 L 450 300" class="arrow"/>
+  
+  <!-- Redis to Subscribers -->
+  <path d="M 550 330 L 690 140" class="arrow"/>
+  <path d="M 550 380 L 690 540" class="arrow"/>
+  
+  <!-- Network Boundaries -->
+  <rect x="20" y="50" width="860" height="580" fill="none" stroke="#666" stroke-width="2" stroke-dasharray="10,5"/>
+  <text x="30" y="70" class="subtitle">Network: Multiple Ruby Processes • Same Machine or Distributed</text>
+  
+  <!-- Channel Details -->
+  <rect x="100" y="230" width="700" height="50" class="channel"/>
+  <text x="450" y="250" text-anchor="middle" class="title">Redis Pub/Sub Channels</text>
+  <text x="150" y="270" class="channel-text">SensorDataMessage: Temperature, Humidity, Light</text>
+  <text x="450" y="270" class="channel-text">SecurityAlertMessage: Motion, Door, Window</text>
+  <text x="750" y="270" class="channel-text">DeviceCommandMessage: HVAC, Lights</text>
+  
+  <!-- Key Features -->
+  <rect x="50" y="640" width="800" height="50" class="redis"/>
+  <text x="70" y="660" class="text">✓ Distributed: Processes can run on different machines</text>
+  <text x="70" y="675" class="text">✓ Real-time: Instant message delivery via Redis pub/sub</text>
+  
+  <text x="450" y="660" class="text">✓ Scalable: Add/remove publishers and subscribers dynamically</text>
+  <text x="450" y="675" class="text">✓ Reliable: Redis handles connection pooling and fault tolerance</text>
+  
+  <text x="650" y="660" class="text">✓ Channel-based: Each message type gets own channel</text>
+  <text x="650" y="675" class="text">✓ Automatic: Message routing handled by Redis</text>
+</svg>

data/examples/{smart_home_iot_dataflow.md → redis/smart_home_iot_dataflow.md}

@@ -6,54 +6,7 @@ This document describes the data flow architecture for the Smart Home IoT exampl
 
 The smart home system consists of three types of IoT devices and a central dashboard, all communicating through Redis pub/sub channels. Each message type uses its own Redis channel for efficient routing and scaling.
 
-```mermaid
-graph TB
-    %% IoT Devices
-    THERM["🌡️ Smart Thermostat<br/>THERM-001<br/>Living Room"]
-    CAM["📹 Security Camera<br/>CAM-001<br/>Front Door"]
-    LOCK["🚪 Smart Door Lock<br/>LOCK-001<br/>Main Entrance"]
-    DASH["📊 IoT Dashboard<br/>System Monitor"]
-
-    %% Redis Channels
-    subgraph REDIS ["Redis Pub/Sub Channels"]
-        SENSOR["SensorDataMessage<br/>Temperature, Motion, Status<br/>Battery Levels"]
-        COMMAND["DeviceCommandMessage<br/>set_temperature, start_recording<br/>lock/unlock, get_status"]
-        ALERT["AlertMessage<br/>Motion Detected, Battery Low<br/>High Temperature"]
-        STATUS["DashboardStatusMessage<br/>System Status, Device Counts<br/>Alert Summaries"]
-    end
-
-    %% Device Publishing
-    THERM -.->|"Temperature Data"| SENSOR
-    CAM -.->|"Motion Data"| SENSOR
-    LOCK -.->|"Lock Status"| SENSOR
-    CAM -.->|"Motion Alerts"| ALERT
-    THERM -.->|"High Temp Alerts"| ALERT
-    LOCK -.->|"Battery Low Alerts"| ALERT
-    DASH -.->|"System Status"| STATUS
-    DASH -.->|"Device Commands"| COMMAND
-
-    %% Device Subscribing
-    COMMAND -->|"set_temperature"| THERM
-    COMMAND -->|"start/stop recording"| CAM
-    COMMAND -->|"lock/unlock"| LOCK
-    SENSOR -->|"All sensor data"| DASH
-    COMMAND -->|"Command logging"| DASH
-    ALERT -->|"All alerts"| DASH
-    STATUS -->|"Status updates"| DASH
-
-    %% Styling
-    classDef deviceStyle fill:#ff6b6b,stroke:#c0392b,stroke-width:2px,color:#fff
-    classDef cameraStyle fill:#4ecdc4,stroke:#16a085,stroke-width:2px,color:#fff
-    classDef lockStyle fill:#ffe66d,stroke:#f39c12,stroke-width:2px,color:#333
-    classDef dashStyle fill:#a8e6cf,stroke:#27ae60,stroke-width:2px,color:#333
-    classDef redisStyle fill:#dc143c,stroke:#a00,stroke-width:2px,color:#fff
-
-    class THERM deviceStyle
-    class CAM cameraStyle
-    class LOCK lockStyle
-    class DASH dashStyle
-    class SENSOR,COMMAND,ALERT,STATUS redisStyle
-```
+![Smart Home System Architecture](smart_home_system_architecture.svg)
 
 ## Message Flow Details
 
@@ -81,24 +34,7 @@ All IoT devices continuously publish sensor readings to the `SensorDataMessage`
 ### 2. Device Command Flow
 The dashboard and external systems send commands to specific devices via the `DeviceCommandMessage` channel:
 
-```mermaid
-sequenceDiagram
-    participant App as Mobile App
-    participant Redis as Redis Channel
-    participant Therm as Thermostat
-    participant Cam as Camera
-    participant Lock as Door Lock
-
-    App->>Redis: DeviceCommandMessage<br/>device_id THERM-001 set_temperature
-    Redis->>Therm: ✅ Processes THERM prefix match
-    Redis->>Cam: ❌ Ignores not CAM prefix
-    Redis->>Lock: ❌ Ignores not LOCK prefix
-    
-    App->>Redis: DeviceCommandMessage<br/>device_id CAM-001 start_recording
-    Redis->>Therm: ❌ Ignores not THERM prefix
-    Redis->>Cam: ✅ Processes CAM prefix match
-    Redis->>Lock: ❌ Ignores not LOCK prefix
-```
+![Device Command Flow](device_command_flow.svg)
 
 **Device Command Filtering Rules:**
 - **THERM-*** devices: Accept `set_temperature`, `get_status`
@@ -108,60 +44,12 @@ sequenceDiagram
 ### 3. Alert System Flow
 Devices publish critical notifications to the `AlertMessage` channel when conditions are detected:
 
-```mermaid
-flowchart LR
-    subgraph Triggers
-        T1[High Temperature > 28°C]
-        T2[Motion Detected]
-        T3[Battery < 20%]
-        T4[Device Offline > 30s]
-    end
-    
-    subgraph Devices
-        THERM2[🌡️ Thermostat]
-        CAM2[📹 Camera]
-        LOCK2[🚪 Door Lock]
-    end
-    
-    subgraph AlertChannel [AlertMessage Channel]
-        A1[Motion Alert]
-        A2[High Temp Alert]
-        A3[Battery Low Alert]
-        A4[Device Offline Alert]
-    end
-    
-    T1 --> THERM2 --> A2
-    T2 --> CAM2 --> A1
-    T3 --> LOCK2 --> A3
-    T4 --> A4
-    
-    AlertChannel --> DASH2[📊 Dashboard]
-```
+![Alert System Flow](alert_system_flow.svg)
 
 ### 4. Dashboard Status Flow
 The dashboard aggregates all system data and publishes periodic status updates:
 
-```mermaid
-graph LR
-    subgraph DataCollection [Data Collection]
-        D1[Device Last Seen Times]
-        D2[Alert Counts]
-        D3[Battery Levels]
-        D4[System Health]
-    end
-    
-    subgraph Processing [Status Processing]
-        P1[Count Active Devices<br/>last_seen < 30s]
-        P2[Count Recent Alerts<br/>last 5 minutes]
-        P3[Calculate Averages]
-    end
-    
-    subgraph Output [Status Output]
-        O1[DashboardStatusMessage<br/>Every 10 seconds]
-    end
-    
-    DataCollection --> Processing --> Output
-```
+![Dashboard Status Flow](dashboard_status_flow.svg)
 
 ## Channel-Based Architecture Benefits
 

data/examples/redis/smart_home_system_architecture.svg

@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="900" height="700" viewBox="0 0 900 700" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .bg { fill: transparent; }
+      .thermostat { fill: #4a2a1a; stroke: #ff6b6b; stroke-width: 2; rx: 8; }
+      .camera { fill: #1a3a3a; stroke: #4ecdc4; stroke-width: 2; rx: 8; }
+      .lock { fill: #3a3a1a; stroke: #ffe66d; stroke-width: 2; rx: 8; }
+      .dashboard { fill: #2a3a2a; stroke: #a8e6cf; stroke-width: 2; rx: 8; }
+      .redis-group { fill: #2a1a1a; stroke: #dc143c; stroke-width: 3; rx: 12; }
+      .channel { fill: #1a1a2a; stroke: #dc143c; stroke-width: 2; rx: 6; }
+      .publish-flow { stroke: #ffaa4a; stroke-width: 2; fill: none; stroke-dasharray: 5,5; }
+      .subscribe-flow { stroke: #4aff4a; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
+      .text { fill: #ffffff; font-family: 'Arial', sans-serif; font-size: 12px; }
+      .title { fill: #4a9eff; font-family: 'Arial', sans-serif; font-size: 18px; font-weight: bold; }
+      .subtitle { fill: #ffaa4a; font-family: 'Arial', sans-serif; font-size: 11px; }
+      .channel-text { fill: #dc143c; font-family: 'Arial', sans-serif; font-size: 10px; }
+      .device-label { fill: #ffffff; font-family: 'Arial', sans-serif; font-size: 10px; }
+    </style>
+    <marker id="arrowhead" markerWidth="8" markerHeight="6" 
+            refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#4aff4a" />
+    </marker>
+  </defs>
+  
+  <!-- Background -->
+  <rect class="bg" width="900" height="700"/>
+  
+  <!-- Title -->
+  <text x="450" y="25" text-anchor="middle" class="title">Smart Home IoT System Architecture</text>
+  <text x="450" y="45" text-anchor="middle" class="subtitle">Redis Pub/Sub Channels for Device Communication</text>
+  
+  <!-- IoT Devices -->
+  <rect x="50" y="100" width="140" height="80" class="thermostat"/>
+  <text x="120" y="125" text-anchor="middle" class="text">🌡️ Smart Thermostat</text>
+  <text x="120" y="145" text-anchor="middle" class="device-label">THERM-001</text>
+  <text x="120" y="160" text-anchor="middle" class="device-label">Living Room</text>
+  
+  <rect x="50" y="220" width="140" height="80" class="camera"/>
+  <text x="120" y="245" text-anchor="middle" class="text">📹 Security Camera</text>
+  <text x="120" y="265" text-anchor="middle" class="device-label">CAM-001</text>
+  <text x="120" y="280" text-anchor="middle" class="device-label">Front Door</text>
+  
+  <rect x="50" y="340" width="140" height="80" class="lock"/>
+  <text x="120" y="365" text-anchor="middle" class="text">🚪 Smart Door Lock</text>
+  <text x="120" y="385" text-anchor="middle" class="device-label">LOCK-001</text>
+  <text x="120" y="400" text-anchor="middle" class="device-label">Main Entrance</text>
+  
+  <rect x="710" y="220" width="140" height="80" class="dashboard"/>
+  <text x="780" y="245" text-anchor="middle" class="text">📊 IoT Dashboard</text>
+  <text x="780" y="265" text-anchor="middle" class="device-label">System Monitor</text>
+  <text x="780" y="280" text-anchor="middle" class="device-label">Central Control</text>
+  
+  <!-- Redis Pub/Sub Channels -->
+  <rect x="300" y="80" width="350" height="380" class="redis-group"/>
+  <text x="475" y="105" text-anchor="middle" class="title">Redis Pub/Sub Channels</text>
+  
+  <!-- Individual channels -->
+  <rect x="320" y="130" width="310" height="50" class="channel"/>
+  <text x="475" y="150" text-anchor="middle" class="text">SensorDataMessage</text>
+  <text x="475" y="170" text-anchor="middle" class="channel-text">Temperature, Motion, Status, Battery Levels</text>
+  
+  <rect x="320" y="200" width="310" height="50" class="channel"/>
+  <text x="475" y="220" text-anchor="middle" class="text">DeviceCommandMessage</text>
+  <text x="475" y="240" text-anchor="middle" class="channel-text">set_temperature, start_recording, lock/unlock, get_status</text>
+  
+  <rect x="320" y="270" width="310" height="50" class="channel"/>
+  <text x="475" y="290" text-anchor="middle" class="text">AlertMessage</text>
+  <text x="475" y="310" text-anchor="middle" class="channel-text">Motion Detected, Battery Low, High Temperature</text>
+  
+  <rect x="320" y="340" width="310" height="50" class="channel"/>
+  <text x="475" y="360" text-anchor="middle" class="text">DashboardStatusMessage</text>
+  <text x="475" y="380" text-anchor="middle" class="channel-text">System Status, Device Counts, Alert Summaries</text>
+  
+  <!-- Device Publishing (dashed lines to channels) -->
+  <path d="M 190 140 L 320 155" class="publish-flow"/>
+  <text x="255" y="135" class="subtitle">Temperature Data</text>
+  
+  <path d="M 190 260 L 320 155" class="publish-flow"/>
+  <text x="255" y="208" class="subtitle">Motion Data</text>
+  
+  <path d="M 190 380 L 320 155" class="publish-flow"/>
+  <text x="255" y="368" class="subtitle">Lock Status</text>
+  
+  <!-- Alert publishing -->
+  <path d="M 190 280 L 320 295" class="publish-flow"/>
+  <path d="M 190 160 L 320 295" class="publish-flow"/>
+  <path d="M 190 400 L 320 295" class="publish-flow"/>
+  
+  <!-- Dashboard publishing -->
+  <path d="M 710 240 L 630 365" class="publish-flow"/>
+  <path d="M 710 260 L 630 225" class="publish-flow"/>
+  
+  <!-- Device subscribing (solid arrows from channels) -->
+  <path d="M 630 225 L 710 140" class="subscribe-flow"/>
+  <text x="670" y="182" class="subtitle">set_temperature</text>
+  
+  <path d="M 630 225 L 710 180" class="subscribe-flow"/>
+  <text x="650" y="202" class="subtitle">start/stop recording</text>
+  
+  <path d="M 630 225 L 710 280" class="subscribe-flow"/>
+  <text x="670" y="252" class="subtitle">lock/unlock</text>
+  
+  <!-- Dashboard subscribing to all data -->
+  <path d="M 630 155 L 710 220" class="subscribe-flow"/>
+  <path d="M 630 295 L 710 240" class="subscribe-flow"/>
+  <path d="M 630 365 L 710 260" class="subscribe-flow"/>
+  <path d="M 630 225 L 710 280" class="subscribe-flow"/>
+  
+  <!-- Channel Benefits -->
+  <rect x="50" y="500" width="800" height="180" fill="#1a1a1a" stroke="#4a9eff" rx="8"/>
+  <text x="70" y="525" class="title">Channel-Based Architecture Benefits</text>
+  
+  <text x="70" y="550" class="text">🎯 Efficient Message Routing:</text>
+  <text x="90" y="565" class="subtitle">• Each message type uses dedicated Redis channel</text>
+  <text x="90" y="580" class="subtitle">• Devices only process relevant messages (no unnecessary filtering)</text>
+  <text x="90" y="595" class="subtitle">• Automatic load balancing through Redis pub/sub mechanism</text>
+  
+  <text x="450" y="550" class="text">🔧 Device-Specific Processing:</text>
+  <text x="470" y="565" class="subtitle">• THERM-* devices process temperature commands only</text>
+  <text x="470" y="580" class="subtitle">• CAM-* devices handle recording commands only</text>
+  <text x="470" y="595" class="subtitle">• LOCK-* devices respond to lock/unlock commands only</text>
+  
+  <text x="70" y="620" class="text">📈 Scalable Architecture:</text>
+  <text x="90" y="635" class="subtitle">• Easy to add new device types with new ID prefixes</text>
+  <text x="90" y="650" class="subtitle">• Multiple instances of same device type supported</text>
+  <text x="90" y="665" class="subtitle">• Dashboard aggregates all data for centralized monitoring</text>
+  
+  <text x="450" y="620" class="text">🔄 Event-Driven Communication:</text>
+  <text x="470" y="635" class="subtitle">• Real-time sensor data publishing every 3-5 seconds</text>
+  <text x="470" y="650" class="subtitle">• Immediate alert generation on threshold conditions</text>
+  <text x="470" y="665" class="subtitle">• Bidirectional command and status flow</text>
+</svg>

data/ideas/README.md

@@ -0,0 +1,41 @@
+# SmartMessage Ideas and Design Discussions
+
+This directory contains design discussions and architectural ideas for extending the SmartMessage framework. Each document explores a different aspect of potential enhancements to the system.
+
+## database_transport.md
+
+Explores implementing a database-backed transport layer for SmartMessage, enabling persistent message queuing and reliable delivery without requiring external message brokers like RabbitMQ or Kafka. This approach would store messages directly in a PostgreSQL or MySQL database, providing built-in persistence, transactional guarantees, and the ability to query message history.
+
+The design includes database schema definitions, message lifecycle management (pending, processing, completed, failed states), retry mechanisms with exponential backoff, and dead letter queue functionality. This transport would be particularly useful for applications that already have a database but don't want the operational complexity of managing a separate message broker, or for scenarios requiring long-term message retention and complex querying capabilities.
+
+## improvement.md
+
+Contains a comprehensive list of potential improvements and enhancements to the SmartMessage framework, covering areas from core functionality to developer experience. The ideas range from technical enhancements like performance optimizations and new transport implementations to architectural improvements such as better plugin systems and schema management.
+
+Key improvement areas include adding support for additional transports (Redis, AWS SQS, Google Pub/Sub), implementing message compression and encryption, enhancing the validation framework, improving error handling and retry logic, and adding comprehensive metrics and monitoring capabilities. The document also explores developer experience improvements like better debugging tools, enhanced documentation, and a potential web UI for message inspection.
+
+## message_discovery.md
+
+Focuses on the service discovery and dynamic class creation capabilities that would allow SmartMessage-based services to automatically discover and use message types from other services without manual integration. This system would enable services to query a central registry to find available message schemas and dynamically create the corresponding Ruby classes at runtime.
+
+The discovery mechanism includes APIs for browsing available message types by service, environment, or tags, dynamic class generation from stored schemas without requiring Ruby source files, and automatic synchronization when schemas are updated. This enables true microservice architectures where services can integrate with new message types without code changes or deployments, supporting patterns like partner integrations, multi-tenant systems, and runtime service composition.
+
+## message_schema.md
+
+Describes a comprehensive schema registry system that transforms SmartMessage from a messaging framework into a schema management platform. The core innovation is bidirectional conversion between SmartMessage Ruby classes and JSON Schema, enabling message definitions to be stored as data rather than code.
+
+The system includes automatic schema registration when classes are defined, version tracking and evolution management, and most importantly, the ability to serialize a Ruby class definition to JSON Schema and reconstruct it later using `to_json_schema` and `from_json_schema` methods. This enables powerful capabilities like storing schemas in databases, sharing schemas across different programming languages (with examples for Rust, Python, TypeScript, Go, and Java), runtime schema updates without deployment, and schema governance with approval workflows. The JSON Schema approach provides cross-language interoperability while maintaining safety (no code execution) and human readability, fundamentally changing how distributed systems manage message contracts.
+
+## meshage.md
+
+Explores implementing a true mesh network transport for SmartMessage that enables completely decentralized messaging with location-agnostic publishing. Unlike direct peer-to-peer systems, mesh networks allow publishers to send messages to service names without knowing which physical nodes host those services - the mesh automatically routes messages through intermediate nodes until they reach their destination or expire.
+
+The design emphasizes the key mesh network principles of complete decentralization, multi-hop message routing, and self-terminating messages with TTL. Services register themselves with the mesh, and the network maintains a distributed service directory that enables automatic route discovery. Messages can travel through multiple intermediate nodes (A → C → F → K) to reach their destination, with the mesh providing fault tolerance through alternate routing paths. The document incorporates insights from existing P2P libraries (journeta, p2p2) for proven patterns in NAT traversal, connection management, and network coordination. Multi-layer deduplication ensures message storms are prevented at subscriber, node, and network levels, while network control messages handle presence, health monitoring, and graceful shutdown protocols.
+
+## agents.md
+
+Comprehensive exploration of AI agents using SmartMessage for intelligent communication patterns. The document examines how AI agents represent the next evolution in distributed systems - intelligent entities that can make contextual decisions, adapt to scenarios, and communicate using natural language understanding combined with structured messaging.
+
+The analysis covers three complementary architecture patterns: Agent99 for request/response service coordination, SmartMessage AI for context-aware dynamic messaging, and hybrid approaches that combine both. Key innovations include contextual message selection where AI chooses appropriate message types based on scenarios, intelligent property generation using LLM understanding of validation constraints, and self-healing validation with automatic retry logic.
+
+The document includes a crucial analysis of Model Context Protocol (MCP) integration, demonstrating how MCP's resource sharing capabilities complement rather than compete with SmartMessage+Agent99. The integration creates a three-layer intelligence stack: Context Layer (MCP) for rich data access, Intelligence Layer (AI + SmartMessage) for smart decision making, and Coordination Layer (Agent99) for multi-agent orchestration. Real-world applications span smart city management, autonomous supply chains, and healthcare coordination systems, showing how these technologies enable truly intelligent distributed systems that understand context, communicate naturally, and coordinate seamlessly.