feat(integration): components now play nicer with each other

readme.hints.md

@@ -741,4 +741,98 @@ The `ts/config/` directory cleanup has been completed. Removed ~500+ lines of un
 - Config directory now contains only 2 files (validator.ts, index.ts)
 - SMS configuration is self-contained in SMS module
 - All deprecated email configuration removed
-- Build passes successfully
+- Build passes successfully
+
+## Per-Domain Rate Limiting (2025-05-29) - COMPLETED
+
+### Overview
+Per-domain rate limiting has been implemented in the UnifiedRateLimiter. Each email domain can have its own rate limits that override global limits.
+
+### Implementation Details
+1. **UnifiedRateLimiter Enhanced:**
+   - Added `domains` property to IHierarchicalRateLimits
+   - Added `domainCounters` Map for tracking domain-specific counters
+   - Added `checkDomainMessageLimit()` method
+   - Added `applyDomainLimits()`, `removeDomainLimits()`, `getDomainLimits()` methods
+
+2. **Domain Rate Limit Configuration:**
+   ```typescript
+   interface IEmailDomainConfig {
+     domain: string;
+     rateLimits?: {
+       outbound?: {
+         messagesPerMinute?: number;
+         messagesPerHour?: number;    // Note: Hour/day limits need additional implementation
+         messagesPerDay?: number;
+       };
+       inbound?: {
+         messagesPerMinute?: number;
+         connectionsPerIp?: number;
+         recipientsPerMessage?: number;
+       };
+     };
+   }
+   ```
+
+3. **Automatic Application:**
+   - UnifiedEmailServer applies domain rate limits during startup
+   - `applyDomainRateLimits()` method converts domain config to rate limiter format
+   - Domain limits override pattern and global limits
+
+4. **Usage Pattern:**
+   ```typescript
+   // Domain configuration with rate limits
+   {
+     domain: 'high-volume.com',
+     dnsMode: 'internal-dns',
+     rateLimits: {
+       outbound: {
+         messagesPerMinute: 200  // Higher than global limit
+       },
+       inbound: {
+         recipientsPerMessage: 100  // Higher recipient limit
+       }
+     }
+   }
+   ```
+
+5. **Rate Limit Precedence:**
+   - Domain-specific limits (highest priority)
+   - Pattern-specific limits
+   - Global limits (lowest priority)
+
+### Integration Status
+- ✅ Rate limiter supports per-domain limits
+- ✅ UnifiedEmailServer applies domain limits on startup
+- ✅ Domain limits properly override global/pattern limits
+- ✅ SMTP server handlers now enforce rate limits (COMPLETED 2025-05-29)
+- ⚠️ Hour/day limits need additional implementation in rate limiter
+
+### SMTP Handler Integration (2025-05-29) - COMPLETED
+Rate limiting is now fully integrated into SMTP server handlers:
+
+1. **UnifiedEmailServer Enhancement:**
+   - Added `getRateLimiter()` method to provide access to the rate limiter
+
+2. **ConnectionManager Integration:**
+   - Replaced custom rate limiting with UnifiedRateLimiter
+   - Now uses `rateLimiter.recordConnection(ip)` for all connection checks
+   - Maintains local IP tracking for resource cleanup only
+
+3. **CommandHandler Integration:**
+   - `handleMailFrom()`: Checks message rate limits with domain context
+   - `handleRcptTo()`: Enforces recipient limits per message
+   - `handleAuth*()`: Records authentication failures and blocks after threshold
+   - Error handling: Records syntax/command errors and blocks after threshold
+
+4. **SMTP Response Codes:**
+   - `421`: Temporary rate limit (client should retry later)
+   - `451`: Temporary recipient rejection
+   - `421 Too many errors`: IP blocked due to excessive errors
+   - `421 Too many authentication failures`: IP blocked due to auth failures
+
+### Next Steps
+The only remaining item is implementing hour/day rate limits in the UnifiedRateLimiter, which would require:
+1. Additional counters for hourly and daily windows
+2. Separate tracking for these longer time periods
+3. Cleanup logic for expired hourly/daily counters