# Phase B: Enhanced Router Integration - Implementation Guide

## Overview

Phase B implements enhanced routing capabilities for the Mercury Device Switch, providing intelligent message routing with load balancing, circuit breaker patterns, and advanced routing strategies while maintaining full backward compatibility with the existing system.

## Architecture

### Enhanced Router System

The enhanced router system consists of four main components:

1. **Enhanced Router** - Core routing engine with multiple strategies
2. **Load Balancer** - Connector health monitoring and distribution
3. **Circuit Breaker** - Resilience and failure protection
4. **Enhanced Configuration** - Centralized configuration management

### Component Relationships

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Switch.Router │───▶│ EnhancedRouter  │───▶│  LoadBalancer   │
│   (Legacy +     │    │  (Strategies)   │    │  (Distribution) │
│    Enhanced)    │    └─────────────────┘    └─────────────────┘
└─────────────────┘              │                       │
        │                        │                       │
        │                        ▼                       ▼
        │              ┌─────────────────┐    ┌─────────────────┐
        └─────────────▶│ CircuitBreaker  │    │   Connectors    │
                       │   (Resilience)  │    │ (Visa/MC/etc.)  │
                       └─────────────────┘    └─────────────────┘
```

## Implementation Details

### 1. Enhanced Router (`lib/da_product_app/switch/enhanced_router.ex`)

**Purpose**: Core routing engine with multiple intelligent routing strategies.

**Key Features**:
- Multiple routing strategies (BIN range, merchant config, processing code, manual)
- Configurable routing policies (load balance, round-robin, weighted, failover)
- Integration with load balancer and circuit breakers
- Comprehensive metrics and monitoring
- Dynamic configuration updates

**Routing Strategies**:

1. **BIN Range Routing**: Routes based on card BIN ranges using the existing MessageRouter
2. **Merchant Config Routing**: Routes based on merchant-specific preferences
3. **Processing Code Routing**: Routes based on transaction processing codes
4. **Manual Routing**: Routes based on explicit destination in context

**Routing Policies**:

1. **Load Balance**: Uses LoadBalancer for intelligent distribution
2. **Round Robin**: Simple round-robin selection
3. **Weighted**: Weighted random selection based on connector weights
4. **Failover**: Primary/secondary failover pattern

**API Methods**:
- `route_message/3` - Route single message
- `route_batch/3` - Route multiple messages efficiently
- `test_routing/3` - Test routing without execution
- `get_routing_status/0` - Get current routing state
- `update_config/1` - Update configuration dynamically
- `get_metrics/0` - Get routing metrics

### 2. Load Balancer (`lib/da_product_app/switch/load_balancer.ex`)

**Purpose**: Manages connector health and distributes load across available connectors.

**Key Features**:
- Multiple load balancing algorithms
- Health monitoring with configurable checks
- Automatic failure detection and recovery
- Performance tracking and metrics
- Dynamic connector management

**Load Balancing Algorithms**:

1. **Round Robin**: Equal distribution across healthy connectors
2. **Weighted**: Distribution based on connector weights and health
3. **Least Connections**: Routes to connector with fewest active connections
4. **Response Time**: Routes to connector with best response time

**Health Management**:
- Periodic health checks
- Failure threshold tracking
- Recovery threshold monitoring
- Connector state management (healthy/degraded/failed)

**API Methods**:
- `select_connector/2` - Select best connector from candidates
- `report_success/3` - Report successful request
- `report_failure/3` - Report failed request
- `health_check/2` - Force health check
- `get_status/1` - Get load balancer status
- `add_connector/3` / `remove_connector/2` - Dynamic connector management

### 3. Circuit Breaker (`lib/da_product_app/switch/circuit_breaker.ex`)

**Purpose**: Implements circuit breaker pattern for connector resilience.

**Key Features**:
- Three states: CLOSED (normal), OPEN (failing), HALF_OPEN (testing)
- Configurable failure thresholds
- Automatic recovery attempts with exponential backoff
- Request timeout handling
- Comprehensive metrics and monitoring

**Circuit States**:

1. **CLOSED**: Normal operation, requests flow through
2. **OPEN**: Connector failing, requests rejected immediately
3. **HALF_OPEN**: Testing recovery, limited requests allowed

**Configuration Options**:
- `failure_threshold` - Failures before opening circuit
- `success_threshold` - Successes needed to close circuit
- `recovery_timeout` - Time before attempting recovery
- `timeout` - Request timeout
- `max_requests_half_open` - Max concurrent requests in half-open

**API Methods**:
- `call/3` - Execute function with circuit breaker protection
- `get_state/1` - Get current circuit state
- `force_open/1` / `force_close/1` - Manual state control
- `reset/1` - Reset to initial state
- `health_check/1` - Perform health check

### 4. Enhanced Configuration (`lib/da_product_app/switch/config.ex`)

**Purpose**: Centralized configuration management for enhanced routing features.

**New Configuration Section**: `get_enhanced_routing_config/0`

**Key Configuration Areas**:

1. **Routing Strategy & Policy**:
   ```elixir
   default_strategy: :bin_range
   default_policy: :load_balance
   ```

2. **Routing Table**:
   ```elixir
   routing_table: %{
     visa_network: [:visa_primary, :visa_secondary],
     mastercard_network: [:mc_primary, :mc_secondary],
     # ... other networks
   }
   ```

3. **Connector Weights**:
   ```elixir
   connector_weights: %{
     visa_primary: 10,
     visa_secondary: 5,
     # ... other connectors
   }
   ```

4. **Merchant Configurations**:
   ```elixir
   merchant_configs: %{
     "MERCHANT001" => %{
       preferred_connectors: [:visa_primary, :mc_primary],
       routing_strategy: :weighted
     }
   }
   ```

5. **Load Balancer Settings**:
   ```elixir
   load_balancer: %{
     algorithm: :weighted,
     health_check_interval: 30_000,
     failure_threshold: 3
   }
   ```

6. **Connector Settings**:
   ```elixir
   connectors: %{
     visa_primary: %{
       weight: 10,
       failure_threshold: 5,
       recovery_timeout: 30_000,
       timeout: 5_000
     }
   }
   ```

### 5. Router Integration (`lib/da_product_app/switch/router.ex`)

**Purpose**: Integrates enhanced routing with existing switch router while maintaining backward compatibility.

**Key Features**:
- Configurable routing system selection (enhanced vs legacy)
- Seamless fallback from enhanced to legacy routing
- Connector mapping between enhanced names and legacy modules
- Context building for enhanced routing
- Performance metrics integration

**Routing Flow**:

1. Check configuration for router type (enhanced/legacy)
2. For enhanced routing:
   - Convert message to ISOMsg format
   - Build routing context
   - Call EnhancedRouter.route_message/3
   - Map connector name to legacy module
   - Execute connector with metrics reporting
   - Handle failures with fallback
3. For legacy routing:
   - Use existing legacy routing logic
   - Maintain backward compatibility

**Connector Mapping**:
```elixir
:visa_primary -> DaProductApp.Switch.Connectors.Visa
:mc_primary -> DaProductApp.Switch.Connectors.Master
:fallback_connector -> DaProductApp.Switch.Connectors.Fallback
```

## Configuration

### Application Configuration

Add to `config/config.exs`:

```elixir
config :da_product_app, :switch_routing,
  router: :enhanced  # or :legacy

config :da_product_app, :enhanced_routing,
  default_strategy: :bin_range,
  default_policy: :load_balance,
  # ... see config.ex for full configuration
```

### Environment-Specific Configuration

**Development** (`config/dev.exs`):
```elixir
config :da_product_app, :enhanced_routing,
  load_balancer: %{
    health_check_interval: 10_000,  # More frequent checks
    failure_threshold: 2            # Lower threshold for testing
  }
```

**Production** (`config/prod.exs`):
```elixir
config :da_product_app, :enhanced_routing,
  load_balancer: %{
    health_check_interval: 60_000,  # Less frequent checks
    failure_threshold: 5            # Higher threshold for stability
  }
```

## Usage Examples

### Basic Routing

```elixir
# Route a single message
message = %{
  "0" => "0200",
  "2" => "4111111111111111",
  "3" => "000000"
}

result = DaProductApp.Switch.Router.route(message)
```

### Enhanced Routing with Context

```elixir
# Route with merchant context
context = %{
  merchant_id: "MERCHANT001",
  terminal_id: "TERMINAL123"
}

options = [strategy: :merchant_config, policy: :weighted]

result = DaProductApp.Switch.EnhancedRouter.route_message(
  iso_message, 
  context, 
  options
)
```

### Test Routing

```elixir
# Test routing without execution
{:ok, routing_info} = DaProductApp.Switch.Router.test_route(message)

IO.inspect(routing_info.routing_system)  # :enhanced or :legacy
IO.inspect(routing_info.connector)       # Selected connector
IO.inspect(routing_info.strategy)        # Strategy used
```

### Get Router Status

```elixir
# Get enhanced router status
status = DaProductApp.Switch.EnhancedRouter.get_routing_status()

IO.inspect(status.connector_statuses)
IO.inspect(status.load_balancer_status)
IO.inspect(status.circuit_breaker_states)
```

### Monitor Load Balancer

```elixir
# Get load balancer metrics
metrics = DaProductApp.Switch.LoadBalancer.get_metrics()

IO.inspect(metrics.total_selections)
IO.inspect(metrics.connector_selections)
```

### Monitor Circuit Breakers

```elixir
# Check circuit breaker status
state_info = DaProductApp.Switch.CircuitBreaker.get_state_info(:visa_primary)

IO.inspect(state_info.state)           # :closed, :open, or :half_open
IO.inspect(state_info.failure_count)
IO.inspect(state_info.metrics)
```

## Testing

### Running Tests

```bash
# Run all Phase B tests
mix test test/da_product_app/switch/

# Run specific component tests
mix test test/da_product_app/switch/enhanced_router_test.exs
mix test test/da_product_app/switch/load_balancer_test.exs
mix test test/da_product_app/switch/circuit_breaker_test.exs
```

### Test Coverage

The test suite covers:

1. **Enhanced Router Tests**:
   - All routing strategies (BIN range, merchant config, processing code)
   - All routing policies (load balance, round-robin, weighted, failover)
   - Batch routing
   - Configuration updates
   - Error handling

2. **Load Balancer Tests**:
   - All load balancing algorithms
   - Health monitoring and failure detection
   - Connector management
   - Metrics collection

3. **Circuit Breaker Tests**:
   - State transitions (closed → open → half-open → closed)
   - Failure threshold handling
   - Recovery timeout behavior
   - Request limiting in half-open state

4. **Router Integration Tests**:
   - Legacy routing compatibility
   - Enhanced routing integration
   - Connector mapping
   - Error handling and fallback

5. **Configuration Tests**:
   - Configuration validation
   - Enhanced routing configuration structure
   - Environment-specific settings

## Migration Strategy

### Phase B.1: Foundation (Current)
- ✅ Enhanced Router implementation
- ✅ Load Balancer implementation  
- ✅ Circuit Breaker implementation
- ✅ Enhanced Configuration
- ✅ Router Integration
- ✅ Comprehensive test suite

### Phase B.2: Advanced Features (Future)
- [ ] Advanced routing rules engine
- [ ] Machine learning-based routing
- [ ] Real-time routing optimization
- [ ] Advanced metrics and dashboards

### Phase B.3: Production Ready (Future)
- [ ] Performance optimization
- [ ] Monitoring integration
- [ ] Alerting system
- [ ] Production hardening

## Backward Compatibility

Phase B maintains full backward compatibility:

1. **Legacy Router**: Existing routing logic preserved
2. **Configuration**: Legacy configuration still works
3. **Connectors**: Existing connector modules unchanged
4. **Message Format**: Legacy message format supported
5. **API**: Existing Router.route/1 API unchanged

## Performance Considerations

1. **Routing Overhead**: Enhanced routing adds minimal latency (~1-2ms)
2. **Memory Usage**: Circuit breakers and load balancer state require additional memory
3. **Health Checks**: Periodic health checks add background processing
4. **Metrics**: Metrics collection has minimal performance impact

## Monitoring and Metrics

### Available Metrics

1. **Enhanced Router**:
   - Total requests
   - Successful/failed routes
   - Strategy usage distribution
   - Connector usage distribution

2. **Load Balancer**:
   - Total selections
   - Connector selections distribution
   - Failed selections
   - Connector health status

3. **Circuit Breaker**:
   - Total requests
   - Successful/failed/rejected requests
   - Average response time
   - State change events

### Monitoring Integration

Metrics can be integrated with:
- Telemetry for real-time monitoring
- Phoenix LiveDashboard for web interface
- External monitoring systems (Prometheus, DataDog, etc.)

## Security Considerations

1. **Configuration Security**: Sensitive connector configurations should be encrypted
2. **Access Control**: Enhanced router management should be restricted
3. **Audit Logging**: All routing decisions should be logged for compliance
4. **Rate Limiting**: Circuit breakers provide natural rate limiting

## Troubleshooting

### Common Issues

1. **Enhanced Routing Not Working**:
   - Check `router: :enhanced` in configuration
   - Verify EnhancedRouter is started
   - Check for configuration errors

2. **Circuit Breakers Always Open**:
   - Check failure thresholds
   - Verify connector health
   - Review timeout settings

3. **Load Balancer Not Selecting Connectors**:
   - Check connector health status
   - Verify candidates list
   - Review algorithm configuration

### Debug Tools

```elixir
# Test routing decisions
DaProductApp.Switch.Router.test_route(message)

# Check router status
DaProductApp.Switch.EnhancedRouter.get_routing_status()

# Force health checks
DaProductApp.Switch.LoadBalancer.health_check(:connector_name)

# Check circuit breaker state
DaProductApp.Switch.CircuitBreaker.get_state_info(:connector_name)
```

## Conclusion

Phase B successfully implements enhanced routing capabilities while maintaining full backward compatibility. The system provides intelligent routing with resilience features and comprehensive monitoring, preparing the Mercury Device Switch for production-scale deployment with advanced routing requirements.