smart_message 0.0.10 → 0.0.12

data/examples/city_scenario/room_for_improvement.md

@@ -0,0 +1,240 @@
+# Room for Improvement - Common Patterns Analysis
+
+## Overview
+Analysis of Ruby service implementations in the multi_program_demo identified several common patterns that could be extracted into reusable mixin modules to reduce code duplication and improve maintainability.
+
+## Common Patterns Identified
+
+### 1. Signal Handlers (100% Duplication)
+All services have identical signal handler setup code:
+```ruby
+def setup_signal_handlers
+  %w[INT TERM].each do |signal|
+    Signal.trap(signal) do
+      puts "\n[emoji] Service shutting down..."
+      logger.info("Service shutting down")
+      exit(0)
+    end
+  end
+end
+```
+**Files affected:** All 6 service files
+
+### 2. Message Header Configuration
+Services follow similar patterns for setting message headers:
+- Setting `from` attribute on message classes
+- Publishing with `_sm_header.from` and `_sm_header.to` assignments
+- Consistent header manipulation patterns
+
+**Files affected:** All services that publish messages
+
+### 3. Active Incident Management
+Fire Department and Police Department share nearly identical patterns:
+- Hash tracking active incidents (`@active_fires`, `@active_incidents`)
+- Resolution checking loops with duration-based logic
+- Unit assignment and return-to-pool mechanisms
+- Publishing `EmergencyResolvedMessage` when resolved
+
+**Shared logic:**
+- `check_fire_resolutions` / `check_incident_resolutions`
+- `resolve_fire` / `resolve_incident`
+- Unit assignment based on severity
+- Duration-based resolution (10-15 seconds)
+
+### 4. Resource Unit Management
+Both emergency services track and manage available units:
+```ruby
+# Fire Department
+@available_engines = ['Engine-1', 'Engine-2', 'Engine-3', 'Ladder-1', 'Rescue-1']
+assigned_engines = @available_engines.take(engines_needed)
+@available_engines = @available_engines.drop(engines_needed)
+
+# Police Department
+@available_units = ['Unit-101', 'Unit-102', 'Unit-103', 'Unit-104']
+assigned_units = @available_units.take(units_needed)
+@available_units = @available_units.drop(units_needed)
+```
+
+### 5. Dispatch Response Handling
+House and LocalBank handle dispatch responses similarly:
+- Display colored output based on priority/severity
+- Log response details
+- Start resolution thread with random delay
+- Update internal state when resolved
+
+### 6. Service Status Pattern
+All services maintain consistent status tracking:
+- `@service_name` instance variable
+- `@status` instance variable ('healthy', 'warning', 'critical', 'failed')
+- `@start_time` timestamp
+- Status determination logic based on service-specific conditions
+
+### 7. Main Service Loop
+Most services share similar loop structure:
+```ruby
+def start_service/start_monitoring/start_operations
+  loop do
+    # Service-specific activity
+    sleep(interval)
+  end
+rescue => e
+  puts "[emoji] Error in service: #{e.message}"
+  logger.error("Error in service: #{e.message}")
+  retry
+end
+```
+
+## Recommended New Mixin Modules
+
+### 1. **Common::SignalHandler**
+**Priority: HIGH** - 100% code duplication
+```ruby
+module Common
+  module SignalHandler
+    def setup_signal_handlers
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) do
+          shutdown_message
+          exit(0)
+        end
+      end
+    end
+    
+    def shutdown_message
+      puts "\n#{service_emoji} #{@service_name} shutting down..."
+      logger.info("#{@service_name} shutting down")
+    end
+  end
+end
+```
+
+### 2. **Common::IncidentManager**
+**Priority: HIGH** - Significant shared logic between Fire/Police
+```ruby
+module Common
+  module IncidentManager
+    def initialize_incident_tracking
+      @active_incidents = {}
+      @available_units = []
+    end
+    
+    def assign_units(units_needed)
+      units_needed = [@available_units.size, units_needed].min
+      assigned = @available_units.shift(units_needed)
+      assigned
+    end
+    
+    def return_units(units)
+      @available_units.concat(units)
+    end
+    
+    def check_incident_resolutions(base_duration = 10..15)
+      @active_incidents.each do |id, incident|
+        duration = (Time.now - incident[:start_time]).to_i
+        if duration > rand(base_duration)
+          resolve_incident(id, incident, duration)
+        end
+      end
+    end
+  end
+end
+```
+
+### 3. **Common::MessageSetup**
+**Priority: MEDIUM** - Reduces boilerplate
+```ruby
+module Common
+  module MessageSetup
+    def setup_message_defaults(*message_classes)
+      message_classes.each do |klass|
+        klass.from = @service_name
+      end
+    end
+    
+    def publish_with_headers(message, to: nil)
+      message._sm_header.from = @service_name
+      message._sm_header.to = to if to
+      message.publish
+    end
+  end
+end
+```
+
+### 4. **Common::DispatchResponder**
+**Priority: MEDIUM** - Shared by House and Bank
+```ruby
+module Common
+  module DispatchResponder
+    def handle_dispatch_response(dispatch, dispatch_type)
+      display_dispatch(dispatch, dispatch_type)
+      log_dispatch(dispatch, dispatch_type)
+      start_resolution_thread(dispatch)
+    end
+    
+    private
+    
+    def display_dispatch(dispatch, type)
+      # Colored output logic
+    end
+    
+    def start_resolution_thread(dispatch)
+      Thread.new do
+        sleep(rand(180..600))
+        resolve_dispatch(dispatch)
+      end
+    end
+  end
+end
+```
+
+### 5. **Common::ServiceLoop**
+**Priority: LOW** - Minor benefit
+```ruby
+module Common
+  module ServiceLoop
+    def run_service_loop(activity_method, sleep_interval)
+      loop do
+        send(activity_method)
+        sleep(sleep_interval)
+      end
+    rescue => e
+      handle_service_error(e)
+      retry
+    end
+    
+    def handle_service_error(error)
+      puts "#{service_emoji} Error in #{@service_name}: #{error.message}"
+      logger.error("Error in #{@service_name}: #{error.message}")
+    end
+  end
+end
+```
+
+## Implementation Priority
+
+1. **Immediate Implementation:**
+   - `Common::SignalHandler` - Zero risk, 100% duplication
+   - `Common::IncidentManager` - High value for Fire/Police departments
+
+2. **Next Phase:**
+   - `Common::MessageSetup` - Simplifies message handling
+   - `Common::DispatchResponder` - Consolidates House/Bank response logic
+
+3. **Consider Later:**
+   - `Common::ServiceLoop` - Minor improvement, may reduce flexibility
+
+## Benefits of Refactoring
+
+- **Reduced Code Duplication:** ~200-300 lines of duplicated code can be eliminated
+- **Consistency:** Ensures all services handle common operations identically
+- **Maintainability:** Bug fixes and improvements in one place benefit all services
+- **Testability:** Common behaviors can be tested once in isolation
+- **Onboarding:** New developers can understand patterns more quickly
+
+## Migration Strategy
+
+1. Start with `Common::SignalHandler` as a proof of concept
+2. Test thoroughly with one service before applying to all
+3. Implement one mixin at a time to avoid breaking changes
+4. Keep service-specific behavior in the service classes
+5. Document the mixins clearly for future developers

data/examples/city_scenario/security_emergency_flow.svg

@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="700" height="500" viewBox="0 0 700 500" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .bg { fill: transparent; }
+      .bank { fill: #3a2a1a; stroke: #ffcc4a; stroke-width: 2; rx: 8; }
+      .police { fill: #1a2a3a; stroke: #4aafff; stroke-width: 2; rx: 8; }
+      .all-services { fill: #2a2a3a; stroke: #4a9eff; stroke-width: 2; rx: 8; }
+      .message { stroke: #ff4a9e; stroke-width: 3; fill: none; marker-end: url(#arrowhead); }
+      .broadcast { stroke: #4aff4a; stroke-width: 2; fill: none; marker-end: url(#arrowhead-green); }
+      .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; }
+      .note { fill: #aaaaaa; font-family: 'Arial', sans-serif; font-size: 10px; }
+      .process { fill: #2a1a3a; stroke: #4aafff; stroke-width: 1; rx: 4; }
+    </style>
+    <marker id="arrowhead" markerWidth="8" markerHeight="6" 
+            refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#ff4a9e" />
+    </marker>
+    <marker id="arrowhead-green" 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="700" height="500"/>
+  
+  <!-- Title -->
+  <text x="350" y="25" text-anchor="middle" class="title">Security Emergency Flow</text>
+  <text x="350" y="45" text-anchor="middle" class="subtitle">Bank Robbery Detection and Police Response</text>
+  
+  <!-- Participants -->
+  <rect x="50" y="80" width="120" height="80" class="bank"/>
+  <text x="110" y="105" text-anchor="middle" class="text">🏦 Bank</text>
+  <text x="110" y="125" text-anchor="middle" class="subtitle">Security System</text>
+  <text x="110" y="145" text-anchor="middle" class="subtitle">Silent Alarm</text>
+  
+  <rect x="290" y="80" width="120" height="80" class="police"/>
+  <text x="350" y="105" text-anchor="middle" class="text">👮 Police</text>
+  <text x="350" y="125" text-anchor="middle" class="text">Department</text>
+  <text x="350" y="145" text-anchor="middle" class="subtitle">Law Enforcement</text>
+  
+  <rect x="530" y="80" width="120" height="80" class="all-services"/>
+  <text x="590" y="105" text-anchor="middle" class="text">📢 All Services</text>
+  <text x="590" y="125" text-anchor="middle" class="subtitle">City Emergency</text>
+  <text x="590" y="145" text-anchor="middle" class="subtitle">Network</text>
+  
+  <!-- Vertical lifelines -->
+  <line x1="110" y1="160" x2="110" y2="450" stroke="#666" stroke-width="2" stroke-dasharray="3,3"/>
+  <line x1="350" y1="160" x2="350" y2="450" stroke="#666" stroke-width="2" stroke-dasharray="3,3"/>
+  <line x1="590" y1="160" x2="590" y2="450" stroke="#666" stroke-width="2" stroke-dasharray="3,3"/>
+  
+  <!-- Message Flow -->
+  <!-- 1. Silent alarm triggered -->
+  <path d="M 110 200 L 350 200" class="message"/>
+  <text x="230" y="195" text-anchor="middle" class="text">SilentAlarmMessage</text>
+  <rect x="160" y="210" width="140" height="50" fill="#1a1a1a" stroke="#ff4a9e" rx="4"/>
+  <text x="230" y="225" text-anchor="middle" class="note">Robbery detected</text>
+  <text x="230" y="240" text-anchor="middle" class="note">Alarm type: break_in/robbery</text>
+  <text x="230" y="255" text-anchor="middle" class="note">Threat level: high/critical</text>
+  
+  <!-- 2. Police assessment -->
+  <rect x="290" y="280" width="120" height="30" class="process"/>
+  <text x="350" y="300" text-anchor="middle" class="note">Assess threat level</text>
+  
+  <rect x="290" y="320" width="120" height="40" class="process"/>
+  <text x="350" y="340" text-anchor="middle" class="note">Assign units:</text>
+  <text x="350" y="355" text-anchor="middle" class="note">Unit-101, Unit-102, SWAT</text>
+  
+  <!-- 3. Police dispatch broadcast -->
+  <path d="M 350 380 L 590 380" class="broadcast"/>
+  <text x="470" y="375" text-anchor="middle" class="text">PoliceDispatchMessage</text>
+  <rect x="420" y="390" width="120" height="40" fill="#2a3a2a" stroke="#4aff4a" rx="4"/>
+  <text x="480" y="405" text-anchor="middle" class="note">Units dispatched</text>
+  <text x="480" y="420" text-anchor="middle" class="note">Priority: emergency/critical</text>
+  
+  <!-- 4. Resolution broadcast -->
+  <path d="M 350 440 L 590 440" class="broadcast"/>
+  <text x="470" y="435" text-anchor="middle" class="text">EmergencyResolvedMessage</text>
+  <text x="470" y="455" text-anchor="middle" class="note">Suspects apprehended • Scene secure</text>
+  
+  <!-- Process flow indicators -->
+  <circle cx="350" cy="320" r="3" fill="#4aafff"/>
+  <circle cx="350" cy="350" r="3" fill="#4aafff"/>
+  
+  <!-- Police units details -->
+  <rect x="50" y="380" width="200" height="80" fill="#1a1a1a" stroke="#4aafff" rx="6"/>
+  <text x="60" y="400" class="text">Police Department Units:</text>
+  <text x="60" y="415" class="note">• Unit-101: First response patrol</text>
+  <text x="60" y="430" class="note">• Unit-102: Backup patrol unit</text>
+  <text x="60" y="445" class="note">• Detective-1: Investigation specialist</text>
+  <text x="60" y="460" class="note">• SWAT-Alpha: Tactical response team</text>
+</svg>

data/examples/city_scenario/service_internal_architecture.svg

@@ -0,0 +1,154 @@
+<?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; }
+      .dispatch-group { fill: #2a1a1a; stroke: #ff4a4a; stroke-width: 2; rx: 12; }
+      .citizen-group { fill: #1a2a1a; stroke: #4aff4a; stroke-width: 2; rx: 12; }
+      .visitor-group { fill: #1a1a2a; stroke: #4a4aff; stroke-width: 2; rx: 12; }
+      .component { fill: #3a3a3a; stroke: #ffaa4a; stroke-width: 1; rx: 6; }
+      .flow { stroke: #ffaa4a; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
+      .text { fill: #ffffff; font-family: 'Arial', sans-serif; font-size: 11px; }
+      .group-title { fill: #4a9eff; font-family: 'Arial', sans-serif; font-size: 14px; font-weight: bold; }
+      .title { fill: #4a9eff; font-family: 'Arial', sans-serif; font-size: 18px; font-weight: bold; }
+      .subtitle { fill: #ffaa4a; font-family: 'Arial', sans-serif; font-size: 12px; }
+    </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">Service Internal Architecture</text>
+  <text x="450" y="45" text-anchor="middle" class="subtitle">Emergency Services Communication System Components</text>
+  
+  <!-- Emergency Dispatch Center Group -->
+  <rect x="50" y="80" width="350" height="200" class="dispatch-group"/>
+  <text x="60" y="100" class="group-title">📞 Emergency Dispatch Center (911)</text>
+  
+  <!-- Dispatch components -->
+  <rect x="70" y="120" width="130" height="40" class="component"/>
+  <text x="135" y="145" text-anchor="middle" class="text">911 Call Listener</text>
+  
+  <rect x="230" y="120" width="130" height="40" class="component"/>
+  <text x="295" y="145" text-anchor="middle" class="text">Call Analysis Engine</text>
+  
+  <rect x="150" y="180" width="130" height="40" class="component"/>
+  <text x="215" y="205" text-anchor="middle" class="text">Department Router</text>
+  
+  <rect x="70" y="240" width="90" height="30" class="component"/>
+  <text x="115" y="260" text-anchor="middle" class="text">Fire Dispatcher</text>
+  
+  <rect x="190" y="240" width="90" height="30" class="component"/>
+  <text x="235" y="260" text-anchor="middle" class="text">Police Dispatcher</text>
+  
+  <rect x="300" y="180" width="90" height="30" class="component"/>
+  <text x="345" y="200" text-anchor="middle" class="text">Call Tracking</text>
+  
+  <rect x="300" y="220" width="90" height="30" class="component"/>
+  <text x="345" y="240" text-anchor="middle" class="text">Statistics Engine</text>
+  
+  <!-- Dispatch flows -->
+  <path d="M 200 140 L 230 140" class="flow"/>
+  <path d="M 295 160 L 215 180" class="flow"/>
+  <path d="M 180 205 L 115 240" class="flow"/>
+  <path d="M 250 205 L 235 240" class="flow"/>
+  <path d="M 280 195 L 300 195" class="flow"/>
+  <path d="M 345 210 L 345 220" class="flow"/>
+  
+  <!-- Citizen Group -->
+  <rect x="50" y="320" width="350" height="160" class="citizen-group"/>
+  <text x="60" y="340" class="group-title">👤 Citizen</text>
+  
+  <!-- Citizen components -->
+  <rect x="70" y="360" width="120" height="30" class="component"/>
+  <text x="130" y="380" text-anchor="middle" class="text">Emergency Scenarios</text>
+  
+  <rect x="210" y="360" width="100" height="30" class="component"/>
+  <text x="260" y="380" text-anchor="middle" class="text">Random Selection</text>
+  
+  <rect x="140" y="410" width="120" height="30" class="component"/>
+  <text x="200" y="430" text-anchor="middle" class="text">911 Call Generator</text>
+  
+  <rect x="280" y="410" width="100" height="30" class="component"/>
+  <text x="330" y="430" text-anchor="middle" class="text">Message Publisher</text>
+  
+  <rect x="70" y="450" width="90" height="20" class="component"/>
+  <text x="115" y="463" text-anchor="middle" class="text">Interactive Mode</text>
+  
+  <rect x="190" y="450" width="90" height="20" class="component"/>
+  <text x="235" y="463" text-anchor="middle" class="text">Automatic Mode</text>
+  
+  <!-- Citizen flows -->
+  <path d="M 190 375 L 210 375" class="flow"/>
+  <path d="M 260 390 L 200 410" class="flow"/>
+  <path d="M 260 425 L 280 425" class="flow"/>
+  <path d="M 115 450 L 235 390" class="flow"/>
+  <path d="M 235 450 L 260 390" class="flow"/>
+  
+  <!-- Smart Visitor Group -->
+  <rect x="450" y="80" width="400" height="400" class="visitor-group"/>
+  <text x="460" y="100" class="group-title">🧑‍💼 Smart Visitor (AI-Powered)</text>
+  
+  <!-- Main AI flow -->
+  <rect x="470" y="120" width="110" height="30" class="component"/>
+  <text x="525" y="140" text-anchor="middle" class="text">Incident Observer</text>
+  
+  <rect x="470" y="170" width="120" height="30" class="component"/>
+  <text x="530" y="190" text-anchor="middle" class="text">AI Message Analyzer</text>
+  
+  <rect x="470" y="220" width="120" height="30" class="component"/>
+  <text x="530" y="240" text-anchor="middle" class="text">RubyLLM Integration</text>
+  
+  <rect x="470" y="270" width="110" height="30" class="component"/>
+  <text x="525" y="290" text-anchor="middle" class="text">Message Generator</text>
+  
+  <rect x="470" y="320" width="110" height="30" class="component"/>
+  <text x="525" y="340" text-anchor="middle" class="text">Emergency Publisher</text>
+  
+  <!-- Secondary AI analysis flow -->
+  <rect x="650" y="170" width="120" height="30" class="component"/>
+  <text x="710" y="190" text-anchor="middle" class="text">Message Discovery</text>
+  
+  <rect x="650" y="220" width="120" height="30" class="component"/>
+  <text x="710" y="240" text-anchor="middle" class="text">Property Analysis</text>
+  
+  <rect x="650" y="270" width="130" height="30" class="component"/>
+  <text x="715" y="290" text-anchor="middle" class="text">AI Content Generation</text>
+  
+  <!-- Visitor flows -->
+  <path d="M 525 150 L 525 170" class="flow"/>
+  <path d="M 530 200 L 530 220" class="flow"/>
+  <path d="M 530 250 L 525 270" class="flow"/>
+  <path d="M 525 300 L 525 320" class="flow"/>
+  
+  <path d="M 710 200 L 710 220" class="flow"/>
+  <path d="M 710 250 L 715 270" class="flow"/>
+  
+  <!-- Cross-connections -->
+  <path d="M 590 185 L 650 185" class="flow"/>
+  <path d="M 650 235 L 590 235" class="flow"/>
+  <path d="M 650 285 L 580 285" class="flow"/>
+  
+  <!-- System Integration Notes -->
+  <rect x="50" y="520" width="800" height="160" fill="#1a1a1a" stroke="#4a9eff" rx="8"/>
+  <text x="70" y="545" class="group-title">System Integration Features</text>
+  
+  <text x="70" y="570" class="text">🔄 Message Flow Coordination:</text>
+  <text x="90" y="585" class="text">• Emergency Dispatch routes calls based on emergency type analysis</text>
+  <text x="90" y="600" class="text">• Citizens can operate in interactive or automatic mode for testing scenarios</text>
+  <text x="90" y="615" class="text">• AI Visitor uses RubyLLM for intelligent message type selection and content generation</text>
+  
+  <text x="450" y="570" class="text">🤖 AI Intelligence Components:</text>
+  <text x="470" y="585" class="text">• Dynamic message discovery analyzes available SmartMessage classes</text>
+  <text x="470" y="600" class="text">• Property analysis determines required fields for each message type</text>
+  <text x="470" y="615" class="text">• Content generation creates realistic data for emergency scenarios</text>
+  
+  <text x="70" y="640" class="text">📊 System Monitoring:</text>
+  <text x="90" y="655" class="text">• Call tracking maintains statistics on emergency response coordination</text>
+  <text x="90" y="670" class="text">• Statistics engine provides performance analytics and response time metrics</text>
+</svg>