smart_message 0.0.10 → 0.0.12

data/docs/{examples.md → getting-started/examples.md}

@@ -20,12 +20,11 @@ class NotificationMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout, loopback: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    notification = new(data)
+  def self.process(decoded_message)
+    notification = decoded_message
     
     case notification.channel
     when 'email'
@@ -88,12 +87,11 @@ class UserRegisteredEvent < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    event = new(data)
+  def self.process(decoded_message)
+    event = decoded_message
     
     # Fan out to multiple handlers
     send_welcome_email(event)
@@ -154,12 +152,12 @@ class WelcomeEmailMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    message = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    message = decoded_message
     
     puts "📧 Sending welcome email to #{message.email} (#{message.name})"
     # Email sending logic here
@@ -173,12 +171,12 @@ class AnalyticsMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    event = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    event = decoded_message
     
     puts "📊 Tracking event: #{event.event_type} for user #{event.user_id}"
     # Analytics tracking logic here
@@ -211,12 +209,12 @@ class OrderCreatedMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    order = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    order = decoded_message
     
     # Validate order
     if valid_order?(order)
@@ -254,12 +252,12 @@ class InventoryReservationMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    reservation = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    reservation = decoded_message
     
     success = reserve_inventory(reservation.items)
     
@@ -291,12 +289,12 @@ class PaymentProcessingMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    payment = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    payment = decoded_message
     
     success = process_payment(payment)
     
@@ -364,12 +362,12 @@ class LogMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout, output: "application.log")
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    log_entry = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    log_entry = decoded_message
     
     formatted_message = format_log_entry(log_entry)
     
@@ -414,12 +412,12 @@ class MetricMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    metric = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    metric = decoded_message
     
     # Store metric (would typically go to monitoring system)
     store_metric(metric)
@@ -498,12 +496,12 @@ class MessageGateway < SmartMessage::Base
   # Receive from one transport
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    gateway_message = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    gateway_message = decoded_message
     
     # Transform and forward to destination system
     case gateway_message.destination_system
@@ -567,8 +565,8 @@ class EmailSystemMessage < SmartMessage::Base
   property :original_payload
   property :source
 
-  def self.process(message_header, message_payload)
-    puts "📧 Email system processed message from #{JSON.parse(message_payload)['source']}"
+  def self.process(decoded_message)
+    puts "📧 Email system processed message from #{decoded_message.source}"
   end
 end
 
@@ -576,8 +574,8 @@ class SMSSystemMessage < SmartMessage::Base
   property :original_payload
   property :source
 
-  def self.process(message_header, message_payload)
-    puts "📱 SMS system processed message from #{JSON.parse(message_payload)['source']}"
+  def self.process(decoded_message)
+    puts "📱 SMS system processed message from #{decoded_message.source}"
   end
 end
 
@@ -587,8 +585,8 @@ class AuditSystemMessage < SmartMessage::Base
   property :source_system
   property :processed_at
 
-  def self.process(message_header, message_payload)
-    puts "📋 Audit system logged event from #{JSON.parse(message_payload)['source_system']}"
+  def self.process(decoded_message)
+    puts "📋 Audit system logged event from #{decoded_message.source_system}"
   end
 end
 
@@ -623,12 +621,12 @@ class ResilientMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    message = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    message = decoded_message
     
     begin
       # Simulate potentially failing operation
@@ -691,12 +689,12 @@ class DeadLetterMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout, output: "dead_letter_queue.log")
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    dead_letter = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    dead_letter = decoded_message
     
     puts "💀 Message sent to dead letter queue:"
     puts "   Original: #{dead_letter.original_message}"
@@ -796,9 +794,9 @@ end
 class TestMessage < SmartMessage::Base
   property :data
   
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    message = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    message = decoded_message
     puts "Processed test message: #{message.data}"
   end
 end
@@ -813,22 +811,46 @@ These examples demonstrate the flexibility and power of SmartMessage for buildin
 
 The `examples/` directory contains complete, runnable programs that demonstrate various SmartMessage features:
 
-### Core Messaging Patterns
-- **`01_point_to_point_orders.rb`** - Point-to-point order processing with payment integration
-- **`02_publish_subscribe_events.rb`** - Event broadcasting to multiple services (email, SMS, audit)
-- **`03_many_to_many_chat.rb`** - Interactive chat system with rooms, bots, and human agents
-
-### Advanced Features
-- **`04_redis_smart_home_iot.rb`** - Redis-based IoT sensor monitoring with real-time data flow
-- **`05_proc_handlers.rb`** - Flexible message handlers (blocks, procs, lambdas, methods)
-- **`06_custom_logger_example.rb`** - Advanced logging with SmartMessage::Logger::Default
-- **`07_error_handling_scenarios.rb`** - Comprehensive validation, version mismatch, and error handling
-- **`08_entity_addressing_basic.rb`** - Basic FROM/TO/REPLY_TO message addressing
-- **`08_entity_addressing_with_filtering.rb`** - Advanced entity-aware message filtering
-- **`09_dead_letter_queue_demo.rb`** - Complete Dead Letter Queue system demonstration
-
-### Interactive Demos
-- **`tmux_chat/`** - Multi-pane terminal visualization of many-to-many messaging with file-based transport
+### Memory Transport Examples
+- **`memory/03_point_to_point_orders.rb`** - Point-to-point order processing with payment integration
+- **`memory/04_publish_subscribe_events.rb`** - Event broadcasting to multiple services (email, SMS, audit)
+- **`memory/05_many_to_many_chat.rb`** - Interactive chat system with rooms, bots, and human agents
+- **`memory/07_proc_handlers_demo.rb`** - Flexible message handlers (blocks, procs, lambdas, methods)
+- **`memory/08_custom_logger_demo.rb`** - Advanced logging with SmartMessage::Logger::Default
+- **`memory/09_error_handling_demo.rb`** - Comprehensive validation, version mismatch, and error handling
+- **`memory/10_entity_addressing_basic.rb`** - Basic FROM/TO/REPLY_TO message addressing
+- **`memory/11_entity_addressing_with_filtering.rb`** - Advanced entity-aware message filtering
+- **`memory/02_dead_letter_queue_demo.rb`** - Complete Dead Letter Queue system demonstration
+- **`memory/01_message_deduplication_demo.rb`** - Message deduplication patterns
+- **`memory/12_regex_filtering_microservices.rb`** - Advanced regex filtering for microservices
+- **`memory/13_header_block_configuration.rb`** - Header and block configuration examples
+- **`memory/14_global_configuration_demo.rb`** - Global configuration management
+- **`memory/15_logger_demo.rb`** - Advanced logging demonstrations
+
+### Redis Transport Examples
+- **`redis/01_smart_home_iot_demo.rb`** - Redis-based IoT sensor monitoring with real-time data flow
+
+### Redis Enhanced Transport Examples
+- **`redis_enhanced/enhanced_01_basic_patterns.rb`** - Basic enhanced transport patterns
+- **`redis_enhanced/enhanced_02_fluent_api.rb`** - Fluent API usage examples
+- **`redis_enhanced/enhanced_03_dual_publishing.rb`** - Dual publishing strategies
+- **`redis_enhanced/enhanced_04_advanced_routing.rb`** - Advanced message routing
+
+### Redis Queue Transport Examples
+- **`redis_queue/01_basic_messaging.rb`** - Basic queue messaging patterns
+- **`redis_queue/02_pattern_routing.rb`** - Pattern-based message routing
+- **`redis_queue/03_fluent_api.rb`** - Fluent API for queue operations
+- **`redis_queue/04_load_balancing.rb`** - Load balancing across workers
+- **`redis_queue/05_microservices.rb`** - Microservices communication
+- **`redis_queue/06_emergency_alerts.rb`** - Emergency alert system
+- **`redis_queue/07_queue_management.rb`** - Queue management utilities
+- **`redis_queue/01_comprehensive_examples.rb`** - Comprehensive feature demonstration
+
+### City Scenario (Comprehensive Demo)
+- **`city_scenario/`** - Complete emergency services simulation with multiple services and AI integration
+
+### Performance Testing
+- **`performance_metrics/`** - Benchmarking tools and performance comparisons
 
 ### Running Examples
 
@@ -836,12 +858,14 @@ The `examples/` directory contains complete, runnable programs that demonstrate
 # Navigate to the SmartMessage directory
 cd smart_message
 
-# Run any example directly
-ruby examples/01_point_to_point_orders.rb
-ruby examples/09_dead_letter_queue_demo.rb
+# Run examples from their respective transport directories
+ruby examples/memory/03_point_to_point_orders.rb
+ruby examples/memory/02_dead_letter_queue_demo.rb
+ruby examples/redis/01_smart_home_iot_demo.rb
+ruby examples/redis_queue/01_basic_messaging.rb
 
-# For tmux chat demo
-cd examples/tmux_chat && ./run_demo.sh
+# For city scenario comprehensive demo
+cd examples/city_scenario && ./start_demo.sh
 ```
 
 Each example is self-contained and includes:
@@ -853,16 +877,18 @@ Each example is self-contained and includes:
 
 ### Example Features Demonstrated
 
-| Example | Transports | Features | Use Case |
-|---------|------------|----------|----------|
-| 01 | STDOUT | Point-to-point, validation | Order processing |
-| 02 | STDOUT | Pub-sub, multiple handlers | Event broadcasting |
-| 03 | Memory | Many-to-many, bots | Chat systems |
-| 04 | Redis | IoT, real-time, addressing | Smart home monitoring |
-| 05 | Memory | Proc handlers, flexibility | Dynamic message handling |
-| 06 | STDOUT | Custom logging, lifecycle | Production logging |
-| 07 | STDOUT | Error handling, validation | Robust message systems |
-| 08 | STDOUT | Entity addressing, filtering | Microservice communication |
-| 09 | Memory | DLQ, circuit breakers, replay | Production reliability |
+| Example | Transport | Features | Use Case |
+|---------|-----------|----------|----------|
+| memory/03 | Memory/STDOUT | Point-to-point, validation | Order processing |
+| memory/04 | Memory/STDOUT | Pub-sub, multiple handlers | Event broadcasting |
+| memory/05 | Memory | Many-to-many, bots | Chat systems |
+| redis/01 | Redis | IoT, real-time, addressing | Smart home monitoring |
+| memory/07 | Memory | Proc handlers, flexibility | Dynamic message handling |
+| memory/08 | Memory/STDOUT | Custom logging, lifecycle | Production logging |
+| memory/09 | Memory/STDOUT | Error handling, validation | Robust message systems |
+| memory/10-11 | Memory/STDOUT | Entity addressing, filtering | Microservice communication |
+| memory/02 | Memory | DLQ, circuit breakers, replay | Production reliability |
+| redis_queue/* | Redis Queue | Load balancing, persistence | Production messaging |
+| city_scenario/* | Redis | AI integration, health monitoring | Emergency services |
 
 These examples provide practical, working code that you can use as a starting point for your own SmartMessage implementations.

data/docs/{getting-started.md → getting-started/quick-start.md}

@@ -1,3 +1,4 @@
+
 # Getting Started with SmartMessage
 
 This guide will help you get up and running with SmartMessage quickly.
@@ -25,7 +26,38 @@ gem install smart_message
 ## Requirements
 
 - Ruby >= 3.0.0
-- No additional system dependencies
+- No additional system dependencies for basic usage
+
+## Transport Options
+
+SmartMessage supports multiple transport layers:
+
+### Built-in Transports
+
+- **Memory Transport** - Perfect for development and testing. No external dependencies required.
+- **STDOUT Transport** - Great for debugging and logging. No external dependencies.
+- **Redis Transport** - Production-ready transport for distributed systems. Requires Redis server.
+
+### Redis Installation (Optional)
+
+The Redis transport is built-in but requires Redis server to be installed. However, **you don't need Redis just to play around** - the Memory transport works great for development and testing.
+
+If you want to use Redis transport:
+
+**macOS:**
+```bash
+brew install redis
+brew services start redis
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get update
+sudo apt-get install redis-server
+```
+
+**Other Transports:**
+Additional transport layers (RabbitMQ, Kafka, etc.) are available as separate plugin repositories. Check the [Transports documentation](../reference/transports.md) for more information.
 
 ## Your First Message
 
@@ -60,14 +92,13 @@ class WelcomeMessage < SmartMessage::Base
   # Configure the transport (where messages go)
   config do
     transport SmartMessage::Transport.create(:stdout, loopback: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
   # Define how to process received messages
-  def self.process(message_header, message_payload)
-    # Decode the message
-    data = JSON.parse(message_payload)
-    welcome = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    welcome = decoded_message
     
     # Process the welcome message
     puts "🎉 Welcome #{welcome.user_name}!"
@@ -186,7 +217,7 @@ Serializers handle message encoding/decoding:
 
 ```ruby
 # JSON serialization (built-in)
-serializer SmartMessage::Serializer::JSON.new
+serializer SmartMessage::Serializer::Json.new
 ```
 
 ### Message Handlers
@@ -265,16 +296,15 @@ payment.to('backup-gateway')  # Override destination
 payment.publish
 ```
 
-For more details, see [Entity Addressing](addressing.md).
+For more details, see [Entity Addressing](../core-concepts/addressing.md).
 
 ## Next Steps
 
 Now that you have the basics working, explore:
 
-- [Architecture Overview](architecture.md) - Understand how SmartMessage works
+- [Architecture Overview](../core-concepts/architecture.md) - Understand how SmartMessage works
 - [Examples](examples.md) - See more practical use cases
-- [Transports](transports.md) - Learn about different transport options
-- [Custom Transports](custom-transports.md) - Build your own transport
+- [Transports](../reference/transports.md) - Learn about different transport options
 
 ## Common Patterns
 
@@ -291,12 +321,12 @@ class NotificationMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 
-  def self.process(message_header, message_payload)
-    data = JSON.parse(message_payload)
-    notification = new(data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    notification = decoded_message
     
     # Send email, SMS, push notification, etc.
     send_notification(notification)
@@ -334,7 +364,7 @@ class EventMessage < SmartMessage::Base
 
   config do
     transport SmartMessage::Transport.create(:stdout, output: 'events.log')
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 end
 
@@ -348,6 +378,5 @@ EventMessage.new(
 
 ## Need Help?
 
-- Check the [Troubleshooting Guide](troubleshooting.md)
-- Review the [API Reference](api-reference.md)
+- Check the [Troubleshooting Guide](../development/troubleshooting.md)
 - Look at more [Examples](examples.md)