# Platform Service - SmartProxy Architecture Update Plan

**Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`**

## Overview

SmartProxy has undergone a major architectural update, moving from a direct port-to-port proxy configuration to a flexible route-based system. This plan outlines the necessary updates to integrate these changes into the platformservice while retaining all SmartProxy functionality.

## New SmartProxy Architecture

### Previous Architecture (Legacy)
```typescript
// Old configuration style
{
  fromPort: 443,
  toPort: 8080,
  targetIP: 'backend.server.com',
  sniEnabled: true,
  domainConfigs: [
    {
      domain: 'example.com',
      target: 'backend1.server.com',
      port: 8081
    }
  ]
}
```

### New Architecture (Route-Based)
```typescript
// New configuration style - FULL SmartProxy functionality
{
  routes: [
    {
      name: 'https-traffic',
      match: {
        ports: 443,
        domains: ['example.com', '*.example.com']
      },
      action: {
        type: 'forward',
        target: {
          host: 'backend.server.com',
          port: 8080
        }
      },
      tls: {
        mode: 'terminate',
        certificate: 'auto'
      }
    }
  ],
  defaults: {
    target: {
      host: 'fallback.server.com',
      port: 8080
    },
    security: {
      ipAllowList: ['192.168.1.0/24'],
      maxConnections: 1000
    }
  }
}
```

## Integration Approach

### 1. Direct SmartProxy Configuration

The DcRouter will expose the full SmartProxy configuration directly, with additional email integration that automatically adds email routes to SmartProxy:

```typescript
export interface IDcRouterOptions {
  /**
   * Full SmartProxy configuration - ALL SmartProxy features available
   * This handles HTTP/HTTPS and general TCP/SNI traffic
   */
  smartProxyConfig?: plugins.smartproxy.ISmartProxyOptions;
  
  /**
   * Email configuration - automatically creates SmartProxy routes for email ports
   */
  emailConfig?: IEmailConfig;
  
  /**
   * Additional configuration options
   */
  tls?: {
    contactEmail: string;
    domain?: string;
    certPath?: string;
    keyPath?: string;
  };
  
  /**
   * DNS server configuration
   */
  dnsServerConfig?: plugins.smartdns.IDnsServerOptions;
}
```

### 2. Email Route Auto-Generation

When email configuration is provided, DcRouter will automatically generate SmartProxy routes for email traffic:

```typescript
private async setupSmartProxy() {
  let routes: plugins.smartproxy.IRouteConfig[] = [];
  let acmeConfig: plugins.smartproxy.IAcmeOptions | undefined;
  
  // If user provides full SmartProxy config, use it directly
  if (this.options.smartProxyConfig) {
    routes = this.options.smartProxyConfig.routes || [];
    acmeConfig = this.options.smartProxyConfig.acme;
  }
  
  // If email config exists, automatically add email routes
  if (this.options.emailConfig) {
    const emailRoutes = this.generateEmailRoutes(this.options.emailConfig);
    routes = [...routes, ...emailRoutes];
  }
  
  // Merge TLS/ACME configuration if provided at root level
  if (this.options.tls && !acmeConfig) {
    acmeConfig = {
      accountEmail: this.options.tls.contactEmail,
      enabled: true,
      useProduction: true,
      autoRenew: true,
      renewThresholdDays: 30
    };
  }
  
  // Initialize SmartProxy with combined configuration
  this.smartProxy = new plugins.smartproxy.SmartProxy({
    ...this.options.smartProxyConfig,
    routes,
    acme: acmeConfig
  });
  
  await this.smartProxy.start();
  logger.info('SmartProxy started with route-based configuration');
}

private generateEmailRoutes(emailConfig: IEmailConfig): plugins.smartproxy.IRouteConfig[] {
  const emailRoutes: plugins.smartproxy.IRouteConfig[] = [];
  
  // Create routes for each email port
  for (const port of emailConfig.ports) {
    // Handle different email ports differently
    switch (port) {
      case 25: // SMTP
        emailRoutes.push({
          name: 'smtp-route',
          match: {
            ports: [25]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost', // Forward to internal email server
              port: 10025 // Internal email server port
            }
          },
          // No TLS termination for port 25 (STARTTLS handled by email server)
          tls: {
            mode: 'passthrough'
          }
        });
        break;
        
      case 587: // Submission
        emailRoutes.push({
          name: 'submission-route',
          match: {
            ports: [587]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost',
              port: 10587
            }
          },
          tls: {
            mode: 'passthrough' // STARTTLS handled by email server
          }
        });
        break;
        
      case 465: // SMTPS
        emailRoutes.push({
          name: 'smtps-route',
          match: {
            ports: [465]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost',
              port: 10465
            }
          },
          tls: {
            mode: 'terminate', // Terminate TLS and re-encrypt to email server
            certificate: 'auto'
          }
        });
        break;
    }
  }
  
  // Add domain-specific email routes if configured
  if (emailConfig.domainRules) {
    for (const rule of emailConfig.domainRules) {
      // Extract domain from pattern (e.g., "*@example.com" -> "example.com")
      const domain = rule.pattern.split('@')[1];
      
      if (domain && rule.mode === 'forward' && rule.target) {
        emailRoutes.push({
          name: `email-forward-${domain}`,
          match: {
            ports: emailConfig.ports,
            domains: [domain]
          },
          action: {
            type: 'forward',
            target: {
              host: rule.target.server,
              port: rule.target.port || 25
            }
          },
          tls: {
            mode: rule.target.useTls ? 'terminate-and-reencrypt' : 'passthrough'
          }
        });
      }
    }
  }
  
  return emailRoutes;
}
```

### 3. Email Server Integration

The email server will run on internal ports and receive traffic from SmartProxy:

```typescript
private async setupUnifiedEmailHandling() {
  if (!this.options.emailConfig) {
    logger.info('No email configuration provided');
    return;
  }

  const emailConfig = this.options.emailConfig;
  
  // Map external ports to internal ports
  const portMapping = {
    25: 10025,   // SMTP
    587: 10587,  // Submission
    465: 10465   // SMTPS
  };
  
  // Create internal email server configuration
  const internalEmailConfig: IEmailConfig = {
    ...emailConfig,
    ports: emailConfig.ports.map(port => portMapping[port] || port + 10000),
    hostname: 'localhost' // Listen on localhost for SmartProxy forwarding
  };
  
  // Initialize email components with internal configuration
  this.domainRouter = new DomainRouter({
    domainRules: emailConfig.domainRules,
    defaultMode: emailConfig.defaultMode,
    defaultServer: emailConfig.defaultServer,
    defaultPort: emailConfig.defaultPort,
    defaultTls: emailConfig.defaultTls
  });
  
  this.unifiedEmailServer = new UnifiedEmailServer({
    ...internalEmailConfig,
    domainRouter: this.domainRouter
  });
  
  await this.unifiedEmailServer.start();
  logger.info('Unified email server started on internal ports');
}
```

## Usage Examples

### Example 1: Combined HTTP and Email Configuration
```typescript
const dcRouter = new DcRouter({
  // Full SmartProxy configuration for HTTP/HTTPS
  smartProxyConfig: {
    routes: [
      {
        name: 'web-traffic',
        match: {
          ports: [80, 443],
          domains: ['www.example.com']
        },
        action: {
          type: 'forward',
          target: {
            host: 'web-backend.example.com',
            port: 8080
          }
        },
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        }
      }
    ],
    acme: {
      accountEmail: 'admin@example.com',
      enabled: true,
      useProduction: true
    }
  },
  
  // Email configuration - automatically creates SmartProxy routes
  emailConfig: {
    ports: [25, 587, 465],
    hostname: 'mail.example.com',
    domainRules: [
      {
        pattern: '*@example.com',
        mode: 'mta',
        mtaOptions: {
          dkimSign: true,
          dkimOptions: {
            domainName: 'example.com',
            keySelector: 'mail',
            privateKey: '...'
          }
        }
      }
    ],
    defaultMode: 'forward',
    defaultServer: 'backup-mail.example.com'
  }
});
```

### Example 2: Advanced SmartProxy Features with Email
```typescript
const dcRouter = new DcRouter({
  smartProxyConfig: {
    routes: [
      // Custom API route with authentication
      {
        name: 'api-route',
        match: {
          ports: 443,
          domains: 'api.example.com',
          path: '/v1/*'
        },
        action: {
          type: 'forward',
          target: {
            host: (context) => {
              // Dynamic host selection based on context
              return context.headers['x-api-version'] === 'v2' 
                ? 'api-v2.backend.com' 
                : 'api-v1.backend.com';
            },
            port: 9090
          }
        },
        security: {
          authentication: {
            type: 'jwt',
            jwtSecret: process.env.JWT_SECRET
          },
          rateLimit: {
            maxRequestsPerMinute: 100,
            maxRequestsPerSecond: 10
          }
        }
      }
    ],
    // Advanced SmartProxy options
    preserveSourceIP: true,
    enableDetailedLogging: true,
    maxConnectionsPerIP: 50,
    connectionRateLimitPerMinute: 1000
  },
  
  // Email automatically integrates with SmartProxy
  emailConfig: {
    ports: [25, 587, 465],
    hostname: 'mail.example.com',
    domainRules: []
  }
});
```

## Key Benefits

1. **Full SmartProxy Power**: All SmartProxy features remain available
2. **Automatic Email Integration**: Email ports are automatically routed through SmartProxy
3. **Unified TLS Management**: SmartProxy handles all TLS termination and certificates
4. **Flexible Configuration**: Mix custom SmartProxy routes with automatic email routes
5. **Performance**: SmartProxy's efficient routing benefits email traffic too

## Implementation Tasks

- [ ] Update DcRouter to preserve full SmartProxy configuration
- [ ] Implement automatic email route generation
- [ ] Configure email server to run on internal ports
- [ ] Test integration between SmartProxy and email server
- [ ] Update documentation with full SmartProxy examples
- [ ] Create migration guide showing how to use new features
- [ ] Test advanced SmartProxy features with email routing
- [ ] Verify TLS handling for different email ports
- [ ] Test domain-specific email routing through SmartProxy

## Notes

- SmartProxy acts as the single entry point for all traffic (HTTP, HTTPS, and email)
- Email server runs on internal ports and receives forwarded traffic from SmartProxy
- TLS termination is handled by SmartProxy where appropriate
- STARTTLS for email is handled by the email server itself
- All SmartProxy features (rate limiting, authentication, dynamic routing) are available