smart_message 0.0.10 → 0.0.12

data/examples/redis_queue/enhanced_04_advanced_routing.rb

@@ -0,0 +1,419 @@
+#!/usr/bin/env ruby
+# examples/redis_queue/enhanced_04_advanced_routing.rb
+# Redis Enhanced Transport - Advanced Routing and Filtering Demo
+
+require_relative '../../lib/smart_message'
+require 'smart_message/transport/redis_enhanced_transport'
+require 'json'
+
+puts "🚀 Redis Enhanced Transport - Advanced Routing Demo"
+puts "=" * 53
+
+# Create enhanced Redis transport
+transport = SmartMessage::Transport::RedisEnhancedTransport.new(
+  url: 'redis://localhost:6379',
+  db: 5,  # Use database 5 for advanced routing examples
+  auto_subscribe: true
+)
+
+#==============================================================================
+# Define Complex Microservices Message Classes
+#==============================================================================
+
+class ApiRequestMessage < SmartMessage::Base
+  from 'api-gateway'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :request_id, required: true
+  property :endpoint, required: true
+  property :method, required: true
+  property :user_id
+  property :service_target, required: true
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "🌐 [API GATEWAY] #{data['method']} #{data['endpoint']}"
+    puts "   Request ID: #{data['request_id']}"
+    puts "   Target: #{data['service_target']}"
+    puts "   User: #{data['user_id'] || 'anonymous'}"
+    puts "   Route: #{header.from} → #{header.to}"
+    puts
+  end
+end
+
+class DatabaseQueryMessage < SmartMessage::Base
+  from 'orm-layer'
+  to 'database-service'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :query_id, required: true
+  property :query_type, required: true  # SELECT, INSERT, UPDATE, DELETE
+  property :table, required: true
+  property :execution_time_ms
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "🗄️  [DATABASE] #{data['query_type']} on #{data['table']}"
+    puts "   Query ID: #{data['query_id']}"
+    puts "   Execution: #{data['execution_time_ms']}ms"
+    puts "   Route: #{header.from} → #{header.to}"
+    puts
+  end
+end
+
+class LogMessage < SmartMessage::Base
+  from 'various-services'
+  to 'log-aggregator'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :log_id, required: true
+  property :level, required: true      # DEBUG, INFO, WARN, ERROR, FATAL
+  property :service, required: true
+  property :message, required: true
+  property :context, default: {}
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    level_emoji = {
+      'DEBUG' => '🔍',
+      'INFO' => 'ℹ️',
+      'WARN' => '⚠️',
+      'ERROR' => '❌',
+      'FATAL' => '💀'
+    }[data['level']] || '📝'
+    
+    puts "#{level_emoji} [LOG AGGREGATOR] #{data['level']} from #{data['service']}"
+    puts "   #{data['message']}"
+    puts "   Context: #{data['context']}" unless data['context'].empty?
+    puts "   Route: #{header.from} → #{header.to}"
+    puts
+  end
+end
+
+class MetricsMessage < SmartMessage::Base
+  from 'monitoring-agents'
+  to 'metrics-collector'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :metric_id, required: true
+  property :metric_name, required: true
+  property :value, required: true
+  property :tags, default: {}
+  property :timestamp, default: -> { Time.now.to_f }
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "📊 [METRICS] #{data['metric_name']}: #{data['value']}"
+    puts "   Tags: #{data['tags']}"
+    puts "   From: #{header.from}"
+    puts
+  end
+end
+
+#==============================================================================
+# Advanced Routing Demonstration Functions
+#==============================================================================
+
+def setup_service_specific_routing(transport)
+  puts "🎯 Setting up service-specific routing patterns..."
+  puts
+  
+  # Route API requests to specific services
+  transport.where.from('api-gateway').to('user-service').subscribe
+  transport.where.from('api-gateway').to('order-service').subscribe
+  transport.where.from('api-gateway').to('payment-service').subscribe
+  
+  puts "✅ API Gateway routing configured for:"
+  puts "   • user-service"
+  puts "   • order-service" 
+  puts "   • payment-service"
+  puts
+  
+  # Database queries from different ORM layers
+  transport.where.from('user-orm').type('DatabaseQueryMessage').subscribe
+  transport.where.from('order-orm').type('DatabaseQueryMessage').subscribe
+  transport.where.from('analytics-orm').type('DatabaseQueryMessage').subscribe
+  
+  puts "✅ Database query routing configured for:"
+  puts "   • user-orm queries"
+  puts "   • order-orm queries"
+  puts "   • analytics-orm queries"
+  puts
+end
+
+def setup_log_level_filtering(transport)
+  puts "📋 Setting up log level filtering patterns..."
+  puts
+  
+  # Different log processing based on level and service
+  transport.subscribe_pattern("logmessage.user_service.log_aggregator")
+  transport.subscribe_pattern("logmessage.payment_service.log_aggregator") 
+  transport.subscribe_pattern("logmessage.critical_service.log_aggregator")
+  
+  puts "✅ Log filtering configured for:"
+  puts "   • user-service logs"
+  puts "   • payment-service logs"
+  puts "   • critical-service logs"
+  puts
+end
+
+def setup_metrics_collection_routing(transport)
+  puts "📈 Setting up metrics collection routing..."
+  puts
+  
+  # Collect metrics from different monitoring agents
+  transport.where.type('MetricsMessage').from('cpu-monitor').subscribe
+  transport.where.type('MetricsMessage').from('memory-monitor').subscribe
+  transport.where.type('MetricsMessage').from('disk-monitor').subscribe
+  transport.where.type('MetricsMessage').from('network-monitor').subscribe
+  
+  puts "✅ Metrics collection configured for:"
+  puts "   • CPU monitoring"
+  puts "   • Memory monitoring"
+  puts "   • Disk monitoring"
+  puts "   • Network monitoring"
+  puts
+end
+
+def demonstrate_dynamic_routing
+  puts "🔄 Demonstrating dynamic routing scenarios..."
+  puts
+  
+  # Scenario 1: API Gateway routes to different services
+  api_requests = [
+    { service: 'user-service', endpoint: '/users/profile', method: 'GET' },
+    { service: 'order-service', endpoint: '/orders/create', method: 'POST' },
+    { service: 'payment-service', endpoint: '/payments/process', method: 'POST' }
+  ]
+  
+  api_requests.each_with_index do |req, i|
+    message = ApiRequestMessage.new(
+      request_id: "REQ-#{Time.now.to_i}-#{i}",
+      endpoint: req[:endpoint],
+      method: req[:method],
+      service_target: req[:service],
+      user_id: "user_#{100 + i}"
+    )
+    message.to(req[:service])  # Dynamic routing
+    message.publish
+    
+    sleep 0.1
+  end
+  
+  puts "✅ Published 3 API requests with dynamic routing"
+  puts
+end
+
+def demonstrate_database_query_routing
+  puts "🗄️  Demonstrating database query routing..."
+  puts
+  
+  queries = [
+    { orm: 'user-orm', type: 'SELECT', table: 'users', time: 15 },
+    { orm: 'order-orm', type: 'INSERT', table: 'orders', time: 8 },
+    { orm: 'analytics-orm', type: 'UPDATE', table: 'metrics', time: 45 }
+  ]
+  
+  queries.each_with_index do |query, i|
+    message = DatabaseQueryMessage.new(
+      query_id: "QRY-#{Time.now.to_i}-#{i}",
+      query_type: query[:type],
+      table: query[:table],
+      execution_time_ms: query[:time]
+    )
+    message.from(query[:orm])  # Dynamic sender
+    message.publish
+    
+    sleep 0.1  
+  end
+  
+  puts "✅ Published 3 database queries from different ORM layers"
+  puts
+end
+
+def demonstrate_log_aggregation_routing
+  puts "📋 Demonstrating log aggregation routing..."
+  puts
+  
+  log_entries = [
+    { service: 'user-service', level: 'INFO', msg: 'User authentication successful' },
+    { service: 'payment-service', level: 'ERROR', msg: 'Credit card validation failed' },
+    { service: 'critical-service', level: 'FATAL', msg: 'Database connection lost' },
+    { service: 'user-service', level: 'DEBUG', msg: 'Cache miss for user profile' }
+  ]
+  
+  log_entries.each_with_index do |log, i|
+    message = LogMessage.new(
+      log_id: "LOG-#{Time.now.to_i}-#{i}",
+      level: log[:level],
+      service: log[:service],
+      message: log[:msg],
+      context: { 
+        thread_id: "thread_#{i}", 
+        request_id: "req_#{100 + i}"
+      }
+    )
+    message.from(log[:service])
+    message.publish
+    
+    sleep 0.1
+  end
+  
+  puts "✅ Published 4 log entries from different services"
+  puts
+end
+
+def demonstrate_metrics_collection
+  puts "📊 Demonstrating metrics collection..."
+  puts
+  
+  metrics = [
+    { agent: 'cpu-monitor', name: 'cpu.usage.percent', value: 78.5, tags: { host: 'web-01' } },
+    { agent: 'memory-monitor', name: 'memory.used.bytes', value: 2147483648, tags: { host: 'web-01' } },
+    { agent: 'disk-monitor', name: 'disk.free.percent', value: 45.2, tags: { mount: '/data' } },
+    { agent: 'network-monitor', name: 'network.bytes.sent', value: 1048576, tags: { interface: 'eth0' } }
+  ]
+  
+  metrics.each_with_index do |metric, i|
+    message = MetricsMessage.new(
+      metric_id: "MET-#{Time.now.to_i}-#{i}",
+      metric_name: metric[:name],
+      value: metric[:value],
+      tags: metric[:tags]
+    )
+    message.from(metric[:agent])
+    message.publish
+    
+    sleep 0.1
+  end
+  
+  puts "✅ Published 4 metrics from different monitoring agents"
+  puts
+end
+
+def show_routing_patterns_summary
+  puts "📋 Active Routing Patterns Summary:"
+  puts "=" * 40
+  puts
+  
+  puts "🎯 Service-to-Service Routing:"
+  puts "   • api-gateway → user-service"
+  puts "   • api-gateway → order-service"
+  puts "   • api-gateway → payment-service"
+  puts
+  
+  puts "🗄️  Database Query Routing:"
+  puts "   • user-orm → database-service"
+  puts "   • order-orm → database-service"
+  puts "   • analytics-orm → database-service"
+  puts
+  
+  puts "📋 Log Aggregation Routing:"
+  puts "   • user-service → log-aggregator"
+  puts "   • payment-service → log-aggregator"
+  puts "   • critical-service → log-aggregator"
+  puts
+  
+  puts "📊 Metrics Collection Routing:"
+  puts "   • cpu-monitor → metrics-collector"
+  puts "   • memory-monitor → metrics-collector"
+  puts "   • disk-monitor → metrics-collector"
+  puts "   • network-monitor → metrics-collector"
+  puts
+end
+
+#==============================================================================
+# Main Demonstration
+#==============================================================================
+
+begin
+  puts "🔧 Checking Redis connection..."
+  unless transport.connected?
+    puts "❌ Redis not available. Please start Redis server:"
+    puts "   brew services start redis  # macOS"
+    puts "   sudo service redis start   # Linux"
+    exit 1
+  end
+  puts "✅ Connected to Redis"
+  puts
+  
+  # Set up advanced routing patterns
+  setup_service_specific_routing(transport)
+  setup_log_level_filtering(transport)
+  setup_metrics_collection_routing(transport)
+  
+  # Subscribe message classes
+  ApiRequestMessage.subscribe
+  DatabaseQueryMessage.subscribe
+  LogMessage.subscribe
+  MetricsMessage.subscribe
+  
+  puts "⏳ Waiting for subscriptions to be established..."
+  sleep 1
+  
+  # Demonstrate different routing scenarios
+  demonstrate_dynamic_routing
+  sleep 0.5
+  
+  demonstrate_database_query_routing
+  sleep 0.5
+  
+  demonstrate_log_aggregation_routing
+  sleep 0.5
+  
+  demonstrate_metrics_collection
+  sleep 1
+  
+  puts "⏳ Processing messages (waiting 3 seconds)..."
+  sleep 3
+  
+  # Show summary
+  show_routing_patterns_summary
+  
+  # Show active pattern subscriptions
+  puts "🔍 Active Pattern Subscriptions:"
+  pattern_subscriptions = transport.instance_variable_get(:@pattern_subscriptions)
+  if pattern_subscriptions && pattern_subscriptions.any?
+    pattern_subscriptions.each_with_index do |pattern, i|
+      puts "   #{i + 1}. #{pattern}"
+    end
+  else
+    puts "   No pattern subscriptions found"
+  end
+  puts
+  
+  puts "🎉 Advanced Routing Demo completed!"
+  puts
+  puts "💡 Advanced Routing Benefits:"
+  puts "   • Precise message targeting with multiple conditions"
+  puts "   • Dynamic routing based on message content"
+  puts "   • Service-specific pattern matching"
+  puts "   • Complex microservices communication patterns"
+  puts "   • Flexible subscription management"
+  
+rescue Interrupt
+  puts "\n👋 Demo interrupted by user"
+rescue => e
+  puts "💥 Error: #{e.message}"
+  puts e.backtrace[0..3]
+ensure
+  puts "\n🧹 Cleaning up..."
+  transport&.disconnect
+  puts "✅ Disconnected from Redis"
+end

data/examples/redis_queue/redis_queue_architecture.svg

@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="900" height="800" viewBox="0 0 900 800" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .bg { fill: transparent; }
+      .producer { fill: #2a3a2a; stroke: #4aff4a; stroke-width: 2; rx: 8; }
+      .consumer { fill: #3a2a3a; stroke: #4a9eff; stroke-width: 2; rx: 8; }
+      .redis { fill: #3a1a1a; stroke: #ff4a4a; stroke-width: 3; rx: 12; }
+      .stream { fill: #1a2a3a; stroke: #ffaa4a; stroke-width: 2; rx: 6; }
+      .group { fill: #2a1a3a; stroke: #aa4aff; stroke-width: 2; rx: 6; }
+      .arrow { stroke: #ffaa4a; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
+      .ack-arrow { stroke: #4aff4a; stroke-width: 2; fill: none; marker-end: url(#ack-arrowhead); stroke-dasharray: 5,3; }
+      .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; }
+      .stream-text { fill: #ffaa4a; font-family: 'Arial', sans-serif; font-size: 10px; }
+      .group-text { fill: #aa4aff; 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>
+    <marker id="ack-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="800"/>
+  
+  <!-- Title -->
+  <text x="450" y="25" text-anchor="middle" class="title">SmartMessage Redis Queue Transport Architecture</text>
+  <text x="450" y="45" text-anchor="middle" class="subtitle">Reliable Message Queuing with Consumer Groups and Acknowledgments</text>
+  
+  <!-- Redis Server (Central Hub) -->
+  <rect x="300" y="320" width="300" height="180" class="redis"/>
+  <text x="450" y="345" text-anchor="middle" class="redis-text">Redis Server (v5.0+)</text>
+  <text x="450" y="365" text-anchor="middle" class="text">Streams + Consumer Groups</text>
+  
+  <!-- Redis Streams -->
+  <rect x="320" y="380" width="260" height="40" class="stream"/>
+  <text x="450" y="395" text-anchor="middle" class="stream-text">Stream: OrderMessage</text>
+  <text x="450" y="410" text-anchor="middle" class="stream-text">Messages: [msg1, msg2, msg3, msg4, ...]</text>
+  
+  <!-- Consumer Groups -->
+  <rect x="320" y="430" width="120" height="60" class="group"/>
+  <text x="380" y="450" text-anchor="middle" class="group-text">Consumer Group:</text>
+  <text x="380" y="465" text-anchor="middle" class="group-text">order_processors</text>
+  <text x="380" y="480" text-anchor="middle" class="group-text">worker-1, worker-2</text>
+  
+  <rect x="460" y="430" width="120" height="60" class="group"/>
+  <text x="520" y="450" text-anchor="middle" class="group-text">Consumer Group:</text>
+  <text x="520" y="465" text-anchor="middle" class="group-text">notification_workers</text>
+  <text x="520" y="480" text-anchor="middle" class="group-text">worker-3, worker-4</text>
+  
+  <!-- Producers -->
+  <rect x="50" y="150" width="150" height="80" class="producer"/>
+  <text x="125" y="175" text-anchor="middle" class="title">Producer 1</text>
+  <text x="125" y="195" text-anchor="middle" class="text">Order API</text>
+  <text x="125" y="215" text-anchor="middle" class="subtitle">Publishes OrderMessage</text>
+  
+  <rect x="50" y="250" width="150" height="80" class="producer"/>
+  <text x="125" y="275" text-anchor="middle" class="title">Producer 2</text>
+  <text x="125" y="295" text-anchor="middle" class="text">User Service</text>
+  <text x="125" y="315" text-anchor="middle" class="subtitle">Publishes UserMessage</text>
+  
+  <rect x="50" y="550" width="150" height="80" class="producer"/>
+  <text x="125" y="575" text-anchor="middle" class="title">Producer 3</text>
+  <text x="125" y="595" text-anchor="middle" class="text">Alert System</text>
+  <text x="125" y="615" text-anchor="middle" class="subtitle">Publishes AlertMessage</text>
+  
+  <!-- Consumers -->
+  <rect x="700" y="150" width="150" height="80" class="consumer"/>
+  <text x="775" y="175" text-anchor="middle" class="title">Worker 1</text>
+  <text x="775" y="195" text-anchor="middle" class="text">Order Processor</text>
+  <text x="775" y="215" text-anchor="middle" class="subtitle">Group: order_processors</text>
+  
+  <rect x="700" y="250" width="150" height="80" class="consumer"/>
+  <text x="775" y="275" text-anchor="middle" class="title">Worker 2</text>
+  <text x="775" y="295" text-anchor="middle" class="text">Order Processor</text>
+  <text x="775" y="315" text-anchor="middle" class="subtitle">Group: order_processors</text>
+  
+  <rect x="700" y="400" width="150" height="80" class="consumer"/>
+  <text x="775" y="425" text-anchor="middle" class="title">Worker 3</text>
+  <text x="775" y="445" text-anchor="middle" class="text">Email Service</text>
+  <text x="775" y="465" text-anchor="middle" class="subtitle">Group: notification_workers</text>
+  
+  <rect x="700" y="550" width="150" height="80" class="consumer"/>
+  <text x="775" y="575" text-anchor="middle" class="title">Worker 4</text>
+  <text x="775" y="595" text-anchor="middle" class="text">SMS Service</text>
+  <text x="775" y="615" text-anchor="middle" class="subtitle">Group: notification_workers</text>
+  
+  <!-- Message Flow Arrows -->
+  <!-- Producers to Redis -->
+  <path d="M 200 190 L 300 380" class="arrow"/>
+  <path d="M 200 290 L 300 400" class="arrow"/>
+  <path d="M 200 590 L 300 420" class="arrow"/>
+  
+  <!-- Redis to Consumers -->
+  <path d="M 600 390 L 700 190" class="arrow"/>
+  <path d="M 600 400 L 700 290" class="arrow"/>
+  <path d="M 600 450 L 700 440" class="arrow"/>
+  <path d="M 600 460 L 700 590" class="arrow"/>
+  
+  <!-- Acknowledgment arrows (dashed green) -->
+  <path d="M 700 210 L 600 410" class="ack-arrow"/>
+  <path d="M 700 310 L 600 410" class="ack-arrow"/>
+  <path d="M 700 460 L 600 470" class="ack-arrow"/>
+  <path d="M 700 610 L 600 470" class="ack-arrow"/>
+  
+  <!-- Message Flow Process -->
+  <rect x="50" y="680" width="800" height="110" class="redis"/>
+  <text x="70" y="705" class="title">Message Flow Process</text>
+  
+  <circle cx="90" cy="730" r="12" fill="#4aff4a"/>
+  <text x="90" y="735" text-anchor="middle" class="text">1</text>
+  <text x="110" y="735" class="text">Producer publishes message to Redis Stream</text>
+  
+  <circle cx="450" cy="730" r="12" fill="#ffaa4a"/>
+  <text x="450" y="735" text-anchor="middle" class="text">2</text>
+  <text x="470" y="735" class="text">Message added to stream with unique ID</text>
+  
+  <circle cx="90" cy="755" r="12" fill="#4a9eff"/>
+  <text x="90" y="760" text-anchor="middle" class="text">3</text>
+  <text x="110" y="760" class="text">Consumer group distributes message to available worker</text>
+  
+  <circle cx="450" cy="755" r="12" fill="#aa4aff"/>
+  <text x="450" y="760" text-anchor="middle" class="text">4</text>
+  <text x="470" y="760" class="text">Worker processes message and sends acknowledgment</text>
+  
+  <circle cx="90" cy="780" r="12" fill="#ff4a4a"/>
+  <text x="90" y="785" text-anchor="middle" class="text">5</text>
+  <text x="110" y="785" class="text">If no ACK received, message redistributed to another worker</text>
+  
+  <!-- Key Features -->
+  <text x="50" y="80" class="title">Key Features:</text>
+  <text x="70" y="100" class="text">✓ Guaranteed Delivery: Messages persist until acknowledged</text>
+  <text x="70" y="115" class="text">✓ Load Balancing: Consumer groups distribute work automatically</text>
+  
+  <text x="450" y="100" class="text">✓ Fault Tolerance: Failed workers don't lose messages</text>
+  <text x="450" y="115" class="text">✓ At-Least-Once: Messages redelivered on failure</text>
+  
+  <text x="650" y="80" class="title">Use Cases:</text>
+  <text x="670" y="100" class="text">• Background job processing</text>
+  <text x="670" y="115" class="text">• Order processing pipelines</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.