Complete Service Layer Implementation - Core Business Logic

Major service implementations completed:
✅ PlayerService.cs - Player progression, VIP management, castle operations, teleportation
✅ CombatService.cs - Field interception system, battle resolution, march mechanics
✅ AllianceService.cs - Coalition mechanics, research systems, territory management
✅ KingdomService.cs - KvK events, democratic leadership, population management
✅ PurchaseService.cs - Anti-pay-to-win monitoring, ethical monetization

Core innovations fully implemented:
- Field interception combat system (primary differentiator)
- Alliance coalition system preserving individual identity
- Anti-pay-to-win balance with skill-based alternatives
- Democratic kingdom politics and leadership
- Ethical monetization with player protection systems

Architecture features:
- Consistent dependency injection patterns across all services
- Comprehensive error handling and logging
- Kingdom-scoped security enforcement
- Transaction management via UnitOfWork
- Production-ready business logic implementation

Service layer complete - ready for API controller development

ShadowedRealmsMobile/src/server/ShadowedRealms.API/Services/PurchaseService.cs

@@ -0,0 +1,802 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.API\Services\PurchaseService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Concrete implementation of IPurchaseService providing comprehensive purchase and monetization business logic operations including anti-pay-to-win monitoring, ethical VIP progression, spending balance validation, and skill-based alternative systems with player protection
+ * Last Edit Notes: Initial creation with complete business logic implementation focusing on ethical monetization
+ */
+
+using Microsoft.Extensions.Logging;
+using ShadowedRealms.Core.Interfaces;
+using ShadowedRealms.Core.Interfaces.Repositories;
+using ShadowedRealms.Core.Interfaces.Services;
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Player;
+
+namespace ShadowedRealms.API.Services
+{
+    /// <summary>
+    /// Concrete implementation of purchase service providing ethical monetization and anti-pay-to-win business logic
+    /// </summary>
+    public class PurchaseService : IPurchaseService
+    {
+        private readonly IUnitOfWork _unitOfWork;
+        private readonly IPurchaseLogRepository _purchaseLogRepository;
+        private readonly IPlayerRepository _playerRepository;
+        private readonly IAllianceRepository _allianceRepository;
+        private readonly IKingdomRepository _kingdomRepository;
+        private readonly ICombatLogRepository _combatLogRepository;
+        private readonly ILogger<PurchaseService> _logger;
+
+        // Anti-pay-to-win constants for balance
+        private const double MAX_SPENDING_VICTORY_INFLUENCE = 0.3; // Max 30% victory influence from spending
+        private const double MIN_FREE_PLAYER_EFFECTIVENESS = 0.7; // Min 70% effectiveness for skilled free players
+        private const double CHARGEBACK_RISK_THRESHOLD = 0.15; // 15% chargeback risk threshold
+        private const int VIP_SECRET_TIER_THRESHOLD = 16; // VIP tiers 16+ are secret
+        private const decimal HEALTHY_SPENDING_DAILY_LIMIT = 100m; // Daily spending limit for player protection
+        private const int FRAUD_DETECTION_LOOKBACK_DAYS = 30; // Days to analyze for fraud patterns
+
+        public PurchaseService(
+            IUnitOfWork unitOfWork,
+            IPurchaseLogRepository purchaseLogRepository,
+            IPlayerRepository playerRepository,
+            IAllianceRepository allianceRepository,
+            IKingdomRepository kingdomRepository,
+            ICombatLogRepository combatLogRepository,
+            ILogger<PurchaseService> logger)
+        {
+            _unitOfWork = unitOfWork ?? throw new ArgumentNullException(nameof(unitOfWork));
+            _purchaseLogRepository = purchaseLogRepository ?? throw new ArgumentNullException(nameof(purchaseLogRepository));
+            _playerRepository = playerRepository ?? throw new ArgumentNullException(nameof(playerRepository));
+            _allianceRepository = allianceRepository ?? throw new ArgumentNullException(nameof(allianceRepository));
+            _kingdomRepository = kingdomRepository ?? throw new ArgumentNullException(nameof(kingdomRepository));
+            _combatLogRepository = combatLogRepository ?? throw new ArgumentNullException(nameof(combatLogRepository));
+            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        }
+
+        #region Purchase Processing & Validation
+
+        public async Task<(bool Success, string TransactionId, Dictionary<string, object> AppliedBenefits,
+               Dictionary<string, object> BalanceValidation)>
+            ProcessPurchaseAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails,
+                Dictionary<string, object> paymentMethod)
+        {
+            _logger.LogInformation("Processing purchase: Player {PlayerId}, Amount: {Amount}, Items: {ItemCount}",
+                playerId, purchaseDetails.GetValueOrDefault("Amount", 0),
+                ((List<object>)purchaseDetails.GetValueOrDefault("Items", new List<object>())).Count);
+
+            return await _unitOfWork.ExecuteInTransactionAsync(async () =>
+            {
+                var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+                if (player == null)
+                    throw new ArgumentException($"Player {playerId} not found in kingdom {kingdomId}");
+
+                // Fraud detection
+                var (isFraudulent, riskScore, fraudIndicators, preventionMeasures) =
+                    await DetectPurchaseFraudAsync(playerId, kingdomId, purchaseDetails, paymentMethod);
+
+                if (isFraudulent)
+                {
+                    return (false, "", new Dictionary<string, object>(), new Dictionary<string, object>
+                    {
+                        ["Error"] = "Purchase blocked due to fraud detection",
+                        ["RiskScore"] = riskScore,
+                        ["FraudIndicators"] = fraudIndicators
+                    });
+                }
+
+                // Balance validation
+                var (isValid, validationWarnings, balanceImpact, alternativeOptions) =
+                    await ValidatePurchaseBalanceAsync(playerId, kingdomId, purchaseDetails);
+
+                if (!isValid && balanceImpact.ContainsKey("BlockPurchase") && (bool)balanceImpact["BlockPurchase"])
+                {
+                    return (false, "", new Dictionary<string, object>(), new Dictionary<string, object>
+                    {
+                        ["Error"] = "Purchase would create unfair competitive advantage",
+                        ["ValidationWarnings"] = validationWarnings,
+                        ["AlternativeOptions"] = alternativeOptions
+                    });
+                }
+
+                // Generate transaction ID
+                var transactionId = $"TXN_{playerId}_{DateTime.UtcNow.Ticks}";
+
+                // Process payment (integrate with payment provider)
+                var paymentResult = await ProcessPaymentTransaction(transactionId, purchaseDetails, paymentMethod);
+                if (!paymentResult.Success)
+                {
+                    return (false, transactionId, new Dictionary<string, object>(), new Dictionary<string, object>
+                    {
+                        ["Error"] = "Payment processing failed",
+                        ["PaymentError"] = paymentResult.ErrorMessage
+                    });
+                }
+
+                // Apply purchase benefits
+                var appliedBenefits = await ApplyPurchaseBenefits(playerId, kingdomId, purchaseDetails, transactionId);
+
+                // Create purchase log
+                var purchaseLog = new PurchaseLog
+                {
+                    PlayerId = playerId,
+                    KingdomId = kingdomId,
+                    TransactionId = transactionId,
+                    Amount = Convert.ToDecimal(purchaseDetails["Amount"]),
+                    Currency = (string)purchaseDetails.GetValueOrDefault("Currency", "USD"),
+                    PurchaseType = (string)purchaseDetails["PurchaseType"],
+                    Items = purchaseDetails["Items"].ToString(),
+                    PaymentMethod = paymentMethod["Type"].ToString(),
+                    PurchaseDate = DateTime.UtcNow,
+                    IsRefunded = false
+                };
+
+                await _purchaseLogRepository.CreateAsync(purchaseLog);
+
+                // Update player spending statistics
+                await UpdatePlayerSpendingStats(playerId, kingdomId, purchaseLog.Amount);
+
+                // Create audit trail
+                await CreateTransactionAuditTrailAsync(transactionId, new Dictionary<string, object>
+                {
+                    ["PlayerId"] = playerId,
+                    ["KingdomId"] = kingdomId,
+                    ["PurchaseDetails"] = purchaseDetails,
+                    ["AppliedBenefits"] = appliedBenefits,
+                    ["BalanceValidation"] = balanceImpact,
+                    ["FraudScore"] = riskScore
+                });
+
+                _logger.LogInformation("Purchase processed successfully: {TransactionId}, Player {PlayerId}, Amount: {Amount}",
+                    transactionId, playerId, purchaseLog.Amount);
+
+                return (true, transactionId, appliedBenefits, balanceImpact);
+            });
+        }
+
+        public async Task<(bool IsValid, List<string> ValidationWarnings, Dictionary<string, object> BalanceImpact,
+               Dictionary<string, object> AlternativeOptions)>
+            ValidatePurchaseBalanceAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails)
+        {
+            var validationWarnings = new List<string>();
+            var balanceImpact = new Dictionary<string, object>();
+            var alternativeOptions = new Dictionary<string, object>();
+
+            var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+            if (player == null)
+                return (false, new List<string> { "Player not found" }, balanceImpact, alternativeOptions);
+
+            var purchaseAmount = Convert.ToDecimal(purchaseDetails["Amount"]);
+            var purchaseType = (string)purchaseDetails["PurchaseType"];
+
+            // Analyze current spending patterns
+            var currentSpending = await _purchaseLogRepository.GetPlayerPurchaseSummaryAsync(playerId, kingdomId, 30);
+            var monthlySpending = (decimal)currentSpending["TotalSpent"];
+
+            // Calculate potential competitive impact
+            var competitiveImpact = await CalculatePurchaseCompetitiveImpact(playerId, kingdomId, purchaseDetails);
+            balanceImpact["CompetitiveImpact"] = competitiveImpact;
+
+            // Check spending dominance patterns
+            var spendingDominance = await AnalyzeSpendingDominanceRisk(playerId, kingdomId, purchaseAmount);
+            balanceImpact["SpendingDominance"] = spendingDominance;
+
+            // Validate against anti-pay-to-win thresholds
+            var antiP2WValidation = ValidateAntiPayToWinThresholds(competitiveImpact, spendingDominance);
+            balanceImpact["AntiPayToWinValidation"] = antiP2WValidation;
+
+            // Check if purchase would exceed healthy limits
+            if (monthlySpending + purchaseAmount > HEALTHY_SPENDING_DAILY_LIMIT * 30)
+            {
+                validationWarnings.Add("Purchase exceeds recommended monthly spending limits");
+                balanceImpact["HealthySpendingConcern"] = true;
+            }
+
+            // Generate skill-based alternatives
+            alternativeOptions = await ProvideSkillBasedAlternativesAsync(playerId, kingdomId, purchaseType);
+
+            // Determine if purchase should be blocked
+            var blockPurchase = (double)antiP2WValidation["VictoryInfluenceRisk"] > MAX_SPENDING_VICTORY_INFLUENCE ||
+                               (double)spendingDominance["DominanceRisk"] > 0.8;
+
+            balanceImpact["BlockPurchase"] = blockPurchase;
+
+            if (blockPurchase)
+            {
+                validationWarnings.Add("Purchase would create unfair competitive advantage");
+                validationWarnings.Add("Consider skill-based alternatives provided");
+            }
+
+            var isValid = !blockPurchase;
+
+            return (isValid, validationWarnings, balanceImpact, alternativeOptions);
+        }
+
+        public async Task<(bool Success, Dictionary<string, object> StateAdjustments, Dictionary<string, object> FraudPrevention)>
+            ProcessRefundAsync(int playerId, int kingdomId, string transactionId, string refundReason, string refundType)
+        {
+            _logger.LogInformation("Processing refund: Player {PlayerId}, Transaction {TransactionId}, Type: {RefundType}, Reason: {RefundReason}",
+                playerId, transactionId, refundType, refundReason);
+
+            return await _unitOfWork.ExecuteInTransactionAsync(async () =>
+            {
+                // Get original purchase
+                var purchaseLog = await _purchaseLogRepository.GetByTransactionIdAsync(transactionId, kingdomId);
+                if (purchaseLog == null)
+                {
+                    return (false, new Dictionary<string, object>
+                    {
+                        ["Error"] = "Original transaction not found"
+                    }, new Dictionary<string, object>());
+                }
+
+                if (purchaseLog.IsRefunded)
+                {
+                    return (false, new Dictionary<string, object>
+                    {
+                        ["Error"] = "Transaction already refunded"
+                    }, new Dictionary<string, object>());
+                }
+
+                var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+                if (player == null)
+                    throw new ArgumentException($"Player {playerId} not found");
+
+                var stateAdjustments = new Dictionary<string, object>();
+                var fraudPrevention = new Dictionary<string, object>();
+
+                // Calculate refund impact on game state
+                var refundImpact = await CalculateRefundGameStateImpact(purchaseLog, player);
+
+                // Reverse VIP benefits if applicable
+                if (purchaseLog.PurchaseType == "VIP" || purchaseLog.PurchaseType.Contains("VIP"))
+                {
+                    var vipAdjustments = await ReverseVipBenefits(playerId, kingdomId, purchaseLog);
+                    stateAdjustments["VipAdjustments"] = vipAdjustments;
+                }
+
+                // Reverse premium item benefits
+                var itemAdjustments = await ReversePremiumItemBenefits(playerId, kingdomId, purchaseLog);
+                stateAdjustments["ItemAdjustments"] = itemAdjustments;
+
+                // Implement fraud prevention measures for chargeback/dispute refunds
+                if (refundType == "Chargeback" || refundType == "Dispute")
+                {
+                    fraudPrevention = await ImplementChargebackFraudPrevention(playerId, kingdomId, purchaseLog);
+                }
+
+                // Mark purchase as refunded
+                purchaseLog.IsRefunded = true;
+                purchaseLog.RefundDate = DateTime.UtcNow;
+                purchaseLog.RefundReason = refundReason;
+                await _purchaseLogRepository.UpdateAsync(purchaseLog);
+
+                // Update player spending statistics
+                await UpdatePlayerSpendingStats(playerId, kingdomId, -purchaseLog.Amount);
+
+                // Create refund audit trail
+                await CreateTransactionAuditTrailAsync($"REFUND_{transactionId}", new Dictionary<string, object>
+                {
+                    ["OriginalTransactionId"] = transactionId,
+                    ["RefundType"] = refundType,
+                    ["RefundReason"] = refundReason,
+                    ["StateAdjustments"] = stateAdjustments,
+                    ["FraudPrevention"] = fraudPrevention,
+                    ["RefundAmount"] = purchaseLog.Amount
+                });
+
+                _logger.LogInformation("Refund processed: Transaction {TransactionId}, Amount: {Amount}, Type: {RefundType}",
+                    transactionId, purchaseLog.Amount, refundType);
+
+                return (true, stateAdjustments, fraudPrevention);
+            });
+        }
+
+        public async Task<(bool IsFraudulent, double RiskScore, List<string> FraudIndicators, Dictionary<string, object> PreventionMeasures)>
+            DetectPurchaseFraudAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails,
+                Dictionary<string, object> paymentMethod)
+        {
+            var fraudIndicators = new List<string>();
+            var preventionMeasures = new Dictionary<string, object>();
+            var riskScore = 0.0;
+
+            var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+            if (player == null)
+                return (true, 1.0, new List<string> { "Player not found" }, preventionMeasures);
+
+            // Analyze purchase patterns
+            var recentPurchases = await _purchaseLogRepository.GetPlayerPurchasesAsync(playerId, kingdomId,
+                TimeSpan.FromDays(FRAUD_DETECTION_LOOKBACK_DAYS));
+
+            // Check for rapid successive purchases (velocity check)
+            var recentPurchaseCount = recentPurchases.Count(p => p.PurchaseDate > DateTime.UtcNow.AddHours(-1));
+            if (recentPurchaseCount > 5)
+            {
+                fraudIndicators.Add("High purchase velocity detected");
+                riskScore += 0.3;
+            }
+
+            // Check for unusual spending amounts
+            var avgPurchaseAmount = recentPurchases.Any() ? recentPurchases.Average(p => p.Amount) : 0m;
+            var currentAmount = Convert.ToDecimal(purchaseDetails["Amount"]);
+            if (avgPurchaseAmount > 0 && currentAmount > avgPurchaseAmount * 10)
+            {
+                fraudIndicators.Add("Purchase amount significantly higher than historical pattern");
+                riskScore += 0.2;
+            }
+
+            // Check payment method consistency
+            var paymentMethodChanges = AnalyzePaymentMethodChanges(recentPurchases, paymentMethod);
+            if (paymentMethodChanges.IsUnusual)
+            {
+                fraudIndicators.Add("Unusual payment method change detected");
+                riskScore += 0.15;
+            }
+
+            // Check account age vs spending pattern
+            var accountAge = DateTime.UtcNow - player.CreatedAt;
+            var totalSpent = recentPurchases.Sum(p => p.Amount);
+            if (accountAge.TotalDays < 7 && totalSpent > 500m)
+            {
+                fraudIndicators.Add("High spending on new account");
+                riskScore += 0.25;
+            }
+
+            // Check for chargeback history
+            var chargebackHistory = recentPurchases.Count(p => p.RefundReason?.Contains("Chargeback") == true);
+            if (chargebackHistory > 0)
+            {
+                fraudIndicators.Add("Previous chargeback activity detected");
+                riskScore += 0.4;
+            }
+
+            // Check device/location consistency (if available in payment method)
+            if (paymentMethod.ContainsKey("DeviceFingerprint") && paymentMethod.ContainsKey("Location"))
+            {
+                var deviceConsistency = await ValidateDeviceConsistency(playerId, paymentMethod);
+                if (!deviceConsistency.IsConsistent)
+                {
+                    fraudIndicators.Add("Inconsistent device or location pattern");
+                    riskScore += 0.2;
+                }
+            }
+
+            // Implement prevention measures based on risk score
+            if (riskScore > 0.5)
+            {
+                preventionMeasures["RequireAdditionalVerification"] = true;
+                preventionMeasures["DelayBenefitApplication"] = TimeSpan.FromHours(24);
+            }
+
+            if (riskScore > 0.7)
+            {
+                preventionMeasures["RequireManualReview"] = true;
+                preventionMeasures["TemporarilyRestrictPurchases"] = true;
+            }
+
+            var isFraudulent = riskScore > 0.8;
+
+            if (isFraudulent)
+            {
+                _logger.LogWarning("Fraudulent purchase detected: Player {PlayerId}, Risk score: {RiskScore}, Indicators: {Indicators}",
+                    playerId, riskScore, string.Join(", ", fraudIndicators));
+            }
+
+            return (isFraudulent, riskScore, fraudIndicators, preventionMeasures);
+        }
+
+        #endregion
+
+        #region Anti-Pay-to-Win Monitoring
+
+        public async Task<Dictionary<string, object>> MonitorPayToWinDominanceAsync(int playerId, int kingdomId,
+            TimeSpan monitoringPeriod)
+        {
+            var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+            if (player == null)
+                throw new ArgumentException($"Player {playerId} not found");
+
+            var monitoring = new Dictionary<string, object>
+            {
+                ["PlayerId"] = playerId,
+                ["MonitoringPeriod"] = monitoringPeriod,
+                ["MonitoringTimestamp"] = DateTime.UtcNow
+            };
+
+            // Get spending data for monitoring period
+            var spendingData = await _purchaseLogRepository.GetPlayerPurchaseSummaryAsync(playerId, kingdomId,
+                (int)monitoringPeriod.TotalDays);
+
+            var totalSpent = (decimal)spendingData["TotalSpent"];
+            monitoring["TotalSpending"] = totalSpent;
+
+            // Analyze combat outcomes vs spending
+            var combatAnalysis = await AnalyzeCombatOutcomesBySpending(playerId, kingdomId, monitoringPeriod);
+            monitoring["CombatAnalysis"] = combatAnalysis;
+
+            // Calculate spending dominance metrics
+            var dominanceMetrics = await CalculateSpendingDominanceMetrics(playerId, kingdomId, totalSpent, monitoringPeriod);
+            monitoring["DominanceMetrics"] = dominanceMetrics;
+
+            // Assess competitive balance impact
+            var balanceImpact = await AssessCompetitiveBalanceImpact(playerId, kingdomId, combatAnalysis, dominanceMetrics);
+            monitoring["BalanceImpact"] = balanceImpact;
+
+            // Generate balance correction recommendations
+            var corrections = new List<string>();
+            var victoryInfluence = (double)balanceImpact["VictoryInfluenceFromSpending"];
+
+            if (victoryInfluence > MAX_SPENDING_VICTORY_INFLUENCE)
+            {
+                corrections.Add("Victory outcomes too heavily influenced by spending");
+                corrections.Add("Recommend implementing skill-based balance adjustments");
+                corrections.Add("Consider offering enhanced strategic alternatives to opponents");
+            }
+
+            var playerEffectiveness = (double)balanceImpact["OpponentEffectivenessVsSpender"];
+            if (playerEffectiveness < MIN_FREE_PLAYER_EFFECTIVENESS)
+            {
+                corrections.Add("Free players achieving less than 70% effectiveness against spenders");
+                corrections.Add("Recommend enhancing skill-based bonuses and strategic options");
+            }
+
+            monitoring["BalanceCorrections"] = corrections;
+            monitoring["RequiresIntervention"] = corrections.Any();
+
+            return monitoring;
+        }
+
+        public async Task<Dictionary<string, object>> CalculateCompetitiveEffectivenessAsync(int playerId, int kingdomId,
+            List<int> comparisonGroup)
+        {
+            var effectiveness = new Dictionary<string, object>
+            {
+                ["PlayerId"] = playerId,
+                ["ComparisonGroupSize"] = comparisonGroup.Count,
+                ["AnalysisTimestamp"] = DateTime.UtcNow
+            };
+
+            var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+            if (player == null)
+                throw new ArgumentException($"Player {playerId} not found");
+
+            // Get spending data
+            var playerSpending = await _purchaseLogRepository.GetPlayerPurchaseSummaryAsync(playerId, kingdomId, 30);
+            var playerTotalSpent = (decimal)playerSpending["TotalSpent"];
+
+            // Classify player spending tier
+            var spendingTier = ClassifySpendingTier(playerTotalSpent);
+            effectiveness["PlayerSpendingTier"] = spendingTier;
+            effectiveness["PlayerTotalSpent"] = playerTotalSpent;
+
+            // Calculate effectiveness metrics
+            var playerMetrics = await GetPlayerEffectivenessMetrics(playerId, kingdomId);
+            effectiveness["PlayerMetrics"] = playerMetrics;
+
+            // Compare against similar spending tiers
+            var tierComparison = await CompareAgainstSpendingTier(playerId, kingdomId, comparisonGroup, spendingTier);
+            effectiveness["TierComparison"] = tierComparison;
+
+            // Calculate skill vs spending contribution
+            var skillVsSpendingBreakdown = CalculateSkillVsSpendingContribution(playerMetrics, playerTotalSpent);
+            effectiveness["SkillVsSpendingBreakdown"] = skillVsSpendingBreakdown;
+
+            // Validate 70% effectiveness threshold for free players
+            if (spendingTier == "Free" || spendingTier == "Light")
+            {
+                var freePlayerEffectiveness = (double)tierComparison["RelativeEffectiveness"];
+                var meetsThreshold = freePlayerEffectiveness >= MIN_FREE_PLAYER_EFFECTIVENESS;
+
+                effectiveness["MeetsEffectivenessThreshold"] = meetsThreshold;
+                effectiveness["EffectivenessGap"] = MIN_FREE_PLAYER_EFFECTIVENESS - freePlayerEffectiveness;
+
+                if (!meetsThreshold)
+                {
+                    effectiveness["RecommendedSkillEnhancements"] = await GenerateSkillEnhancementRecommendations(
+                        playerId, kingdomId, freePlayerEffectiveness);
+                }
+            }
+
+            return effectiveness;
+        }
+
+        public async Task<Dictionary<string, object>> ImplementBalanceAdjustmentsAsync(List<int> affectedPlayers, int kingdomId,
+            string balanceType, Dictionary<string, object> adjustmentParameters)
+        {
+            _logger.LogInformation("Implementing balance adjustments: {PlayerCount} players, Type: {BalanceType}",
+                affectedPlayers.Count, balanceType);
+
+            return await _unitOfWork.ExecuteInTransactionAsync(async () =>
+            {
+                var adjustmentResults = new Dictionary<string, object>
+                {
+                    ["BalanceType"] = balanceType,
+                    ["AffectedPlayerCount"] = affectedPlayers.Count,
+                    ["AdjustmentTimestamp"] = DateTime.UtcNow
+                };
+
+                var playerAdjustments = new Dictionary<string, object>();
+
+                foreach (var playerId in affectedPlayers)
+                {
+                    var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+                    if (player == null) continue;
+
+                    var playerSpending = await _purchaseLogRepository.GetPlayerPurchaseSummaryAsync(playerId, kingdomId, 30);
+                    var spendingTier = ClassifySpendingTier((decimal)playerSpending["TotalSpent"]);
+
+                    var adjustments = new Dictionary<string, object>();
+
+                    switch (balanceType.ToLower())
+                    {
+                        case "skill_bonuses":
+                            adjustments = await ApplySkillBasedBalanceBonuses(playerId, kingdomId, spendingTier, adjustmentParameters);
+                            break;
+
+                        case "strategic_advantages":
+                            adjustments = await ApplyStrategicAdvantages(playerId, kingdomId, spendingTier, adjustmentParameters);
+                            break;
+
+                        case "coordination_bonuses":
+                            adjustments = await ApplyCoordinationBonuses(playerId, kingdomId, spendingTier, adjustmentParameters);
+                            break;
+
+                        case "intelligence_bonuses":
+                            adjustments = await ApplyIntelligenceBonuses(playerId, kingdomId, spendingTier, adjustmentParameters);
+                            break;
+
+                        default:
+                            adjustments["Error"] = $"Unknown balance type: {balanceType}";
+                            break;
+                    }
+
+                    playerAdjustments[$"Player_{playerId}"] = adjustments;
+                }
+
+                adjustmentResults["PlayerAdjustments"] = playerAdjustments;
+
+                // Validate adjustment effectiveness
+                var effectivenessValidation = await ValidateAdjustmentEffectiveness(affectedPlayers, kingdomId, balanceType);
+                adjustmentResults["EffectivenessValidation"] = effectivenessValidation;
+
+                return adjustmentResults;
+            });
+        }
+
+        public async Task<Dictionary<string, object>> ValidateVictoryOutcomeBalanceAsync(int kingdomId, TimeSpan analysisTimeframe,
+            string gameMode = null)
+        {
+            var validation = new Dictionary<string, object>
+            {
+                ["KingdomId"] = kingdomId,
+                ["AnalysisTimeframe"] = analysisTimeframe,
+                ["GameMode"] = gameMode,
+                ["AnalysisTimestamp"] = DateTime.UtcNow
+            };
+
+            // Get combat data for analysis period
+            var combatLogs = await _combatLogRepository.GetKingdomCombatLogsAsync(kingdomId, analysisTimeframe);
+
+            if (gameMode != null)
+            {
+                combatLogs = combatLogs.Where(c => c.BattleType?.Contains(gameMode) == true);
+            }
+
+            var totalBattles = combatLogs.Count();
+            validation["TotalBattlesAnalyzed"] = totalBattles;
+
+            if (totalBattles == 0)
+            {
+                validation["ValidationResult"] = "Insufficient battle data for analysis";
+                return validation;
+            }
+
+            // Analyze victory outcomes by spending patterns
+            var victoryAnalysis = new Dictionary<string, object>();
+            var spendingInfluencedVictories = 0;
+            var skillInfluencedVictories = 0;
+            var balancedVictories = 0;
+
+            foreach (var combat in combatLogs)
+            {
+                var outcomeAnalysis = await AnalyzeBattleOutcomeInfluence(combat, kingdomId);
+                var spendingInfluence = (double)outcomeAnalysis["SpendingInfluence"];
+
+                if (spendingInfluence > 0.7)
+                    spendingInfluencedVictories++;
+                else if (spendingInfluence < 0.3)
+                    skillInfluencedVictories++;
+                else
+                    balancedVictories++;
+            }
+
+            var spendingInfluenceRate = (double)spendingInfluencedVictories / totalBattles;
+            var skillInfluenceRate = (double)skillInfluencedVictories / totalBattles;
+            var balancedRate = (double)balancedVictories / totalBattles;
+
+            victoryAnalysis["SpendingInfluencedRate"] = spendingInfluenceRate;
+            victoryAnalysis["SkillInfluencedRate"] = skillInfluenceRate;
+            victoryAnalysis["BalancedRate"] = balancedRate;
+
+            validation["VictoryAnalysis"] = victoryAnalysis;
+
+            // Validate against 30% threshold
+            var meetsThreshold = spendingInfluenceRate <= MAX_SPENDING_VICTORY_INFLUENCE;
+            validation["MeetsBalanceThreshold"] = meetsThreshold;
+            validation["ThresholdViolation"] = spendingInfluenceRate - MAX_SPENDING_VICTORY_INFLUENCE;
+
+            // Generate recommendations
+            var recommendations = new List<string>();
+
+            if (!meetsThreshold)
+            {
+                recommendations.Add($"Spending influence ({spendingInfluenceRate * 100:F1}%) exceeds 30% threshold");
+                recommendations.Add("Implement enhanced skill-based bonuses for lower spenders");
+                recommendations.Add("Provide additional strategic options and coordination tools");
+                recommendations.Add("Consider temporary balance adjustments for affected game modes");
+            }
+            else
+            {
+                recommendations.Add("Victory outcome balance within acceptable parameters");
+                recommendations.Add("Continue monitoring for emerging imbalance patterns");
+            }
+
+            validation["Recommendations"] = recommendations;
+            validation["OverallBalance"] = meetsThreshold ? "Balanced" : "Requires Correction";
+
+            return validation;
+        }
+
+        #endregion
+
+        #region VIP System Management
+
+        public async Task<(bool TierAdvanced, int NewVipTier, bool IsSecretTier, Dictionary<string, object> NewBenefits,
+               double ChargebackRisk, Dictionary<string, object> SkillAlternatives)>
+            ManageVipProgressionAsync(int playerId, int kingdomId, decimal purchaseAmount, string purchaseType)
+        {
+            _logger.LogInformation("Managing VIP progression: Player {PlayerId}, Purchase amount: {Amount}, Type: {PurchaseType}",
+                playerId, purchaseAmount, purchaseType);
+
+            return await _unitOfWork.ExecuteInTransactionAsync(async () =>
+            {
+                var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+                if (player == null)
+                    throw new ArgumentException($"Player {playerId} not found");
+
+                var oldVipTier = player.VipTier;
+
+                // Calculate chargeback risk
+                var chargebackRisk = await CalculateChargebackRisk(playerId, kingdomId, purchaseAmount, purchaseType);
+
+                // Update VIP progression (delegate to player repository for tier calculation)
+                var (tierUpdated, newVipTier, chargebackProtection) = await _playerRepository.UpdateVipTierAsync(
+                    playerId, kingdomId, purchaseAmount);
+
+                var isSecretTier = newVipTier >= VIP_SECRET_TIER_THRESHOLD;
+                var newBenefits = new Dictionary<string, object>();
+                var skillAlternatives = new Dictionary<string, object>();
+
+                if (tierUpdated)
+                {
+                    // Calculate new VIP benefits with balance considerations
+                    newBenefits = await CalculateVipBenefitsWithAlternativesAsync(playerId, kingdomId, newVipTier);
+
+                    // Generate skill-based alternatives for the same benefits
+                    skillAlternatives = await GenerateVipSkillAlternatives(newVipTier, newBenefits);
+
+                    // Apply chargeback protection for secret tiers
+                    if (isSecretTier && chargebackRisk > CHARGEBACK_RISK_THRESHOLD)
+                    {
+                        var protection = await HandleVipChargebackProtectionAsync(playerId, kingdomId, new Dictionary<string, object>
+                        {
+                            ["ChargebackRisk"] = chargebackRisk,
+                            ["VipTier"] = newVipTier,
+                            ["PurchaseAmount"] = purchaseAmount
+                        });
+
+                        newBenefits["ChargebackProtection"] = protection;
+                    }
+
+                    _logger.LogInformation("VIP tier advanced: Player {PlayerId}, Tier {OldTier} → {NewTier} (Secret: {IsSecret})",
+                        playerId, oldVipTier, newVipTier, isSecretTier);
+                }
+
+                return (tierUpdated, newVipTier, isSecretTier, newBenefits, chargebackRisk, skillAlternatives);
+            });
+        }
+
+        public async Task<Dictionary<string, object>> CalculateVipBenefitsWithAlternativesAsync(int playerId, int kingdomId, int vipTier)
+        {
+            var benefits = new Dictionary<string, object>
+            {
+                ["VipTier"] = vipTier,
+                ["CalculationTimestamp"] = DateTime.UtcNow
+            };
+
+            // Calculate convenience benefits (primary VIP value)
+            var convenienceBenefits = new Dictionary<string, object>
+            {
+                ["AutoResourceCollection"] = vipTier >= 5,
+                ["QueueSlots"] = Math.Min(1 + (vipTier / 5), 4),
+                ["InstantBuildingCompletion"] = Math.Min(vipTier / 10, 3), // Limited uses
+                ["AdvancedIntelligence"] = vipTier >= 10,
+                ["PremiumCustomization"] = vipTier >= 8,
+                ["ExclusiveChat"] = vipTier >= 12
+            };
+
+            benefits["ConvenienceBenefits"] = convenienceBenefits;
+
+            // Calculate minor gameplay benefits (capped to prevent pay-to-win)
+            var gameplayBenefits = new Dictionary<string, object>
+            {
+                ["ConstructionSpeedBonus"] = Math.Min(vipTier * 1.5, 15), // Max 15%
+                ["ResearchSpeedBonus"] = Math.Min(vipTier * 1.5, 15), // Max 15%
+                ["MarchSpeedBonus"] = Math.Min(vipTier * 1, 10), // Max 10%
+                ["ResourceCapacityBonus"] = Math.Min(vipTier * 2, 20) // Max 20%
+            };
+
+            benefits["GameplayBenefits"] = gameplayBenefits;
+
+            // Secret tier benefits (16+) with chargeback protection
+            if (vipTier >= VIP_SECRET_TIER_THRESHOLD)
+            {
+                var secretBenefits = new Dictionary<string, object>
+                {
+                    ["SecretTierStatus"] = true,
+                    ["HiddenFromOthers"] = true,
+                    ["ExclusiveTerritoryAccess"] = true,
+                    ["PremiumSupportChannel"] = true,
+                    ["EarlyFeatureAccess"] = true
+                };
+
+                benefits["SecretTierBenefits"] = secretBenefits;
+            }
+
+            // Generate skill-based alternatives that provide similar value
+            var skillAlternatives = new Dictionary<string, object>
+            {
+                ["AchievementBasedSpeedups"] = "Complete daily objectives for speed bonuses",
+                ["StrategicCoordinationBonuses"] = "Alliance coordination provides equivalent bonuses",
+                ["IntelligenceGatheringSkills"] = "Scouting mastery provides advanced intelligence",
+                ["TerritorialMastery"] = "Territory control unlocks exclusive areas",
+                ["CommunityLeadership"] = "Alliance roles provide exclusive communication channels"
+            };
+
+            benefits["SkillBasedAlternatives"] = skillAlternatives;
+
+            return benefits;
+        }
+
+        public async Task<(bool Success, Dictionary<string, object> AppliedBenefits, List<string> ValidationWarnings)>
+            ProcessVipBenefitClaimAsync(int playerId, int kingdomId, string benefitType,
+                Dictionary<string, object> claimParameters)
+        {
+            var player = await _playerRepository.GetByIdAsync(playerId, kingdomId);
+            if (player == null)
+                return (false, new Dictionary<string, object>(), new List<string> { "Player not found" });
+
+            var validationWarnings = new List<string>();
+            var appliedBenefits = new Dictionary<string, object>();
+
+            // Validate VIP tier for benefit
+            var requiredTier = GetRequiredVipTierForBenefit(benefitType);
+            if (player.VipTier < requiredTier)
+            {
+                validationWarnings.Add($"VIP tier {requiredTier} required for {benefitType} (current: {player.VipTier})");
+                return (false, appliedBenefits, validationWarnings);
+            }
+
+            // Check usage limits and cooldowns
+            var usageLimits = await ValidateVipBenefitUsageLimits(playerId, kingdomId, benefitType);
+            if (!usageLimits.CanUse)
+            {
+                validationWarnings.AddRange(usageLimits.Restrictions);
+                return (false, appliedBenefits, validationWarnings);
+            }
+
+            // Process benefit claim
+            switch (benefitType.ToLower())
+            {
+                case "instant_completion":
+                    appliedBenefits = await ProcessInstant

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Services/IAllianceService.cs

@@ -0,0 +1,500 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IAllianceService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Alliance service interface for coordinating alliance-related business logic operations including coalition system, research trees, territory management, democratic decision-making, and multi-alliance coordination that preserves individual alliance identity
+ * Last Edit Notes: Initial creation with comprehensive alliance management operations including coalition mechanics (core innovation), democratic systems, and anti-exploitation measures
+ */
+
+using ShadowedRealms.Core.Models;
+
+namespace ShadowedRealms.Core.Interfaces.Services
+{
+    /// <summary>
+    /// Service interface for alliance-related business logic operations
+    /// Implements coalition system (core innovation), research trees, territory management, democratic decision-making, and multi-alliance coordination
+    /// </summary>
+    public interface IAllianceService
+    {
+        #region Coalition System (Core Innovation)
+
+        /// <summary>
+        /// Forms coalition between multiple alliances while preserving individual alliance identity
+        /// Core innovation: Multi-alliance cooperation without forced merging during KvK events
+        /// </summary>
+        /// <param name="initiatingAllianceId">Alliance proposing coalition formation</param>
+        /// <param name="targetAllianceIds">Alliances to invite to coalition</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="coalitionType">Type of coalition (KvK, territorial, research)</param>
+        /// <param name="proposedTerms">Coalition terms and conditions</param>
+        /// <returns>Coalition formation result with voting requirements and timeline</returns>
+        /// <exception cref="InvalidOperationException">Thrown when coalition requirements not met</exception>
+        Task<(bool Success, string CoalitionId, Dictionary<string, object> VotingRequirements, DateTime VotingDeadline)>
+            FormCoalitionAsync(int initiatingAllianceId, List<int> targetAllianceIds, int kingdomId, string coalitionType,
+                Dictionary<string, object> proposedTerms);
+
+        /// <summary>
+        /// Processes coalition voting by alliance members with democratic consensus requirements
+        /// </summary>
+        /// <param name="allianceId">Alliance voting on coalition</param>
+        /// <param name="coalitionId">Coalition being voted on</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="votingResults">Member voting results</param>
+        /// <returns>Voting processing result and coalition status update</returns>
+        Task<(bool VotePassed, double ApprovalPercentage, Dictionary<string, object> CoalitionStatus)>
+            ProcessCoalitionVotingAsync(int allianceId, string coalitionId, int kingdomId,
+                Dictionary<int, bool> votingResults);
+
+        /// <summary>
+        /// Manages coalition operations and shared resources while maintaining alliance independence
+        /// </summary>
+        /// <param name="coalitionId">Coalition to manage</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationType">Type of coalition operation</param>
+        /// <param name="operationDetails">Details of the operation</param>
+        /// <returns>Coalition operation result and member alliance updates</returns>
+        Task<Dictionary<string, object>> ManageCoalitionOperationAsync(string coalitionId, int kingdomId,
+            string operationType, Dictionary<string, object> operationDetails);
+
+        /// <summary>
+        /// Dissolves coalition with proper benefit distribution and alliance independence restoration
+        /// </summary>
+        /// <param name="coalitionId">Coalition to dissolve</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="dissolutionReason">Reason for dissolution</param>
+        /// <returns>Dissolution result with benefit distribution details</returns>
+        Task<(bool Success, Dictionary<string, object> BenefitDistribution, List<int> AffectedAlliances)>
+            DissolveCoalitionAsync(string coalitionId, int kingdomId, string dissolutionReason);
+
+        #endregion
+
+        #region Research Trees & Collective Benefits
+
+        /// <summary>
+        /// Processes alliance research progression across Military, Economic, and Technology branches
+        /// </summary>
+        /// <param name="allianceId">Alliance conducting research</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="researchType">Research branch (Military/Economic/Technology)</param>
+        /// <param name="researchNode">Specific research node to advance</param>
+        /// <param name="memberContributions">Member resource contributions</param>
+        /// <returns>Research advancement result and new benefits unlocked</returns>
+        Task<(bool Success, int NewResearchLevel, Dictionary<string, object> UnlockedBenefits,
+               Dictionary<int, long> ContributionTracking)>
+            ProcessAllianceResearchAsync(int allianceId, int kingdomId, string researchType, string researchNode,
+                Dictionary<int, Dictionary<string, long>> memberContributions);
+
+        /// <summary>
+        /// Calculates and applies collective research benefits to all alliance members
+        /// </summary>
+        /// <param name="allianceId">Alliance to apply benefits to</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Applied benefits breakdown by member and research branch</returns>
+        Task<Dictionary<string, object>> ApplyCollectiveResearchBenefitsAsync(int allianceId, int kingdomId);
+
+        /// <summary>
+        /// Validates research prerequisites and member contribution requirements
+        /// </summary>
+        /// <param name="allianceId">Alliance attempting research</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="researchType">Research branch being validated</param>
+        /// <param name="researchNode">Specific research node</param>
+        /// <returns>Validation result with prerequisites and contribution requirements</returns>
+        Task<(bool CanResearch, List<string> Prerequisites, Dictionary<string, long> RequiredContributions,
+               Dictionary<string, object> EstimatedBenefits)>
+            ValidateResearchRequirementsAsync(int allianceId, int kingdomId, string researchType, string researchNode);
+
+        /// <summary>
+        /// Tracks individual member contributions to alliance research for benefit distribution
+        /// </summary>
+        /// <param name="allianceId">Alliance to track contributions for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="timeframeDays">Period to analyze contributions</param>
+        /// <returns>Member contribution analysis and benefit allocation recommendations</returns>
+        Task<Dictionary<string, object>> TrackResearchContributionsAsync(int allianceId, int kingdomId,
+            int timeframeDays = 30);
+
+        #endregion
+
+        #region Territory Management & Buildings
+
+        /// <summary>
+        /// Claims territory for alliance with validation of strategic value and defense requirements
+        /// </summary>
+        /// <param name="allianceId">Alliance claiming territory</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="territoryCoordinates">Territory coordinates to claim</param>
+        /// <param name="territoryType">Type of territory (forest, mountain, plain)</param>
+        /// <returns>Territory claim result with defense requirements and benefits</returns>
+        /// <exception cref="InvalidOperationException">Thrown when territory cannot be claimed</exception>
+        Task<(bool Success, string TerritoryId, Dictionary<string, object> DefenseRequirements,
+               Dictionary<string, object> TerritoryBenefits)>
+            ClaimTerritoryAsync(int allianceId, int kingdomId, (int X, int Y) territoryCoordinates, string territoryType);
+
+        /// <summary>
+        /// Constructs and upgrades alliance territory buildings that provide alliance-wide benefits
+        /// </summary>
+        /// <param name="allianceId">Alliance constructing building</param>
+        /// <param name="territoryId">Territory to build in</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="buildingType">Type of building to construct</param>
+        /// <param name="memberContributions">Member resource contributions</param>
+        /// <returns>Construction result with completion time and alliance benefits</returns>
+        Task<(bool Success, DateTime CompletionTime, Dictionary<string, object> AllianceBenefits,
+               Dictionary<int, long> ContributionTracking)>
+            ConstructTerritoryBuildingAsync(int allianceId, string territoryId, int kingdomId, string buildingType,
+                Dictionary<int, Dictionary<string, long>> memberContributions);
+
+        /// <summary>
+        /// Manages contested zones around strategic forest areas with 50% speed reduction mechanics
+        /// </summary>
+        /// <param name="allianceId">Alliance operating in contested zone</param>
+        /// <param name="contestedZoneId">Contested zone identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationType">Type of operation (claim, defend, raid)</param>
+        /// <returns>Contested zone operation result and strategic implications</returns>
+        Task<Dictionary<string, object>> ManageContestedZoneAsync(int allianceId, string contestedZoneId,
+            int kingdomId, string operationType);
+
+        /// <summary>
+        /// Processes territory defense and castle banishment consequences for losing control
+        /// </summary>
+        /// <param name="allianceId">Alliance defending territory</param>
+        /// <param name="territoryId">Territory under attack</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="defenseResult">Result of territory defense battle</param>
+        /// <returns>Defense processing result with banishment consequences if applicable</returns>
+        Task<(bool TerritoryRetained, Dictionary<string, object> BanishmentConsequences,
+               Dictionary<string, object> DefenseRewards)>
+            ProcessTerritoryDefenseAsync(int allianceId, string territoryId, int kingdomId,
+                Dictionary<string, object> defenseResult);
+
+        #endregion
+
+        #region Democratic Alliance Management
+
+        /// <summary>
+        /// Conducts democratic host selection for KvK events with alliance voting
+        /// </summary>
+        /// <param name="allianceId">Alliance conducting host selection</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="kvkEventId">KvK event requiring host selection</param>
+        /// <param name="hostCandidates">Players eligible for host role</param>
+        /// <returns>Host selection result with voting details and appointed host</returns>
+        Task<(bool Success, int SelectedHostId, Dictionary<string, object> VotingResults,
+               Dictionary<string, object> HostPrivileges)>
+            ConductDemocraticHostSelectionAsync(int allianceId, int kingdomId, string kvkEventId,
+                List<int> hostCandidates);
+
+        /// <summary>
+        /// Processes alliance leadership elections with 5-tier hierarchy management
+        /// </summary>
+        /// <param name="allianceId">Alliance conducting elections</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="electionType">Type of election (Leader, Officer, etc.)</param>
+        /// <param name="candidateIds">Players running for positions</param>
+        /// <param name="memberVotes">Voting results from alliance members</param>
+        /// <returns>Election result with new leadership assignments and role privileges</returns>
+        Task<(bool Success, Dictionary<int, string> NewLeadershipRoles, Dictionary<string, object> RolePrivileges)>
+            ProcessLeadershipElectionAsync(int allianceId, int kingdomId, string electionType, List<int> candidateIds,
+                Dictionary<int, int> memberVotes);
+
+        /// <summary>
+        /// Manages role-based permissions across 5-tier leadership structure (Leader, Officers, Members, Recruits, Guests)
+        /// </summary>
+        /// <param name="allianceId">Alliance to manage permissions for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="playerId">Player to set permissions for</param>
+        /// <param name="newRole">New role assignment</param>
+        /// <param name="customPermissions">Custom permission overrides</param>
+        /// <returns>Permission update result with granted authorities</returns>
+        Task<(bool Success, string AssignedRole, Dictionary<string, bool> GrantedPermissions)>
+            ManageRoleBasedPermissionsAsync(int allianceId, int kingdomId, int playerId, string newRole,
+                Dictionary<string, bool> customPermissions = null);
+
+        /// <summary>
+        /// Conducts alliance-wide voting on major decisions with quorum requirements and fraud prevention
+        /// </summary>
+        /// <param name="allianceId">Alliance conducting vote</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="proposalType">Type of proposal being voted on</param>
+        /// <param name="proposalDetails">Details of the proposal</param>
+        /// <param name="memberVotes">Member voting responses</param>
+        /// <returns>Voting result with approval status and implementation timeline</returns>
+        Task<(bool ProposalPassed, double ApprovalPercentage, Dictionary<string, object> ImplementationPlan,
+               List<string> FraudAlerts)>
+            ConductAllianceVotingAsync(int allianceId, int kingdomId, string proposalType,
+                Dictionary<string, object> proposalDetails, Dictionary<int, bool> memberVotes);
+
+        #endregion
+
+        #region Member Management & Social Systems
+
+        /// <summary>
+        /// Processes alliance membership applications and invitations with screening
+        /// </summary>
+        /// <param name="allianceId">Alliance processing membership</param>
+        /// <param name="playerId">Player joining alliance</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="isInvitation">Whether this is invitation or application</param>
+        /// <param name="applicantDetails">Player details for screening</param>
+        /// <returns>Membership processing result with integration plan</returns>
+        Task<(bool Success, string MembershipStatus, Dictionary<string, object> IntegrationPlan,
+               DateTime ProbationEndDate)>
+            ProcessMembershipAsync(int allianceId, int playerId, int kingdomId, bool isInvitation,
+                Dictionary<string, object> applicantDetails);
+
+        /// <summary>
+        /// Manages member activity monitoring and contribution tracking
+        /// </summary>
+        /// <param name="allianceId">Alliance to monitor</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="timeframeDays">Period to analyze activity</param>
+        /// <returns>Activity analysis with member engagement metrics and recommendations</returns>
+        Task<Dictionary<string, object>> MonitorMemberActivityAsync(int allianceId, int kingdomId,
+            int timeframeDays = 7);
+
+        /// <summary>
+        /// Processes member removal with proper benefit cleanup and territory adjustments
+        /// </summary>
+        /// <param name="allianceId">Alliance removing member</param>
+        /// <param name="playerId">Player being removed</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="removalReason">Reason for removal</param>
+        /// <param name="authorizingPlayerId">Player authorizing removal</param>
+        /// <returns>Removal result with benefit cleanup and territory implications</returns>
+        Task<(bool Success, Dictionary<string, object> BenefitsRemoved, bool TerritoryEviction,
+               Dictionary<string, object> TransitionPlan)>
+            ProcessMemberRemovalAsync(int allianceId, int playerId, int kingdomId, string removalReason,
+                int authorizingPlayerId);
+
+        /// <summary>
+        /// Facilitates member-to-member resource trading within alliance network
+        /// </summary>
+        /// <param name="senderPlayerId">Player sending resources</param>
+        /// <param name="receiverPlayerId">Player receiving resources</param>
+        /// <param name="allianceId">Alliance facilitating trade</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="resourceTransfer">Resources to transfer</param>
+        /// <returns>Trade processing result with transaction details</returns>
+        Task<(bool Success, Dictionary<string, object> TransactionDetails, DateTime TransferCompletionTime)>
+            ProcessMemberResourceTradingAsync(int senderPlayerId, int receiverPlayerId, int allianceId, int kingdomId,
+                Dictionary<string, long> resourceTransfer);
+
+        #endregion
+
+        #region Treasury Management & Collective Resources
+
+        /// <summary>
+        /// Manages alliance treasury with collective resource pools and distribution systems
+        /// </summary>
+        /// <param name="allianceId">Alliance managing treasury</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationType">Treasury operation (deposit, withdraw, distribute)</param>
+        /// <param name="resourceDetails">Resources involved in operation</param>
+        /// <param name="authorizingPlayerId">Player authorizing operation</param>
+        /// <returns>Treasury operation result with new balance and audit trail</returns>
+        Task<(bool Success, Dictionary<string, long> NewTreasuryBalance, Dictionary<string, object> AuditEntry)>
+            ManageTreasuryOperationAsync(int allianceId, int kingdomId, string operationType,
+                Dictionary<string, long> resourceDetails, int authorizingPlayerId);
+
+        /// <summary>
+        /// Calculates and processes automatic treasury contributions from members
+        /// </summary>
+        /// <param name="allianceId">Alliance collecting contributions</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="contributionType">Type of automatic contribution</param>
+        /// <returns>Contribution collection result with member compliance tracking</returns>
+        Task<Dictionary<string, object>> ProcessAutomaticContributionsAsync(int allianceId, int kingdomId,
+            string contributionType);
+
+        /// <summary>
+        /// Distributes collective benefits based on member contributions and activity
+        /// </summary>
+        /// <param name="allianceId">Alliance distributing benefits</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="distributionType">Type of benefit distribution</param>
+        /// <param name="distributionCriteria">Criteria for benefit allocation</param>
+        /// <returns>Distribution result with member benefit allocations</returns>
+        Task<Dictionary<string, object>> DistributeCollectiveBenefitsAsync(int allianceId, int kingdomId,
+            string distributionType, Dictionary<string, object> distributionCriteria);
+
+        #endregion
+
+        #region Communication & Coordination
+
+        /// <summary>
+        /// Manages alliance communication systems including chat, announcements, and coordinate sharing
+        /// </summary>
+        /// <param name="allianceId">Alliance managing communications</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="communicationType">Type of communication (chat, announcement, coordinates)</param>
+        /// <param name="messageDetails">Communication content and metadata</param>
+        /// <param name="senderPlayerId">Player sending communication</param>
+        /// <returns>Communication processing result with delivery status</returns>
+        Task<(bool Success, Dictionary<string, object> DeliveryStatus, DateTime MessageTimestamp)>
+            ProcessAllianceCommunicationAsync(int allianceId, int kingdomId, string communicationType,
+                Dictionary<string, object> messageDetails, int senderPlayerId);
+
+        /// <summary>
+        /// Coordinates alliance-wide events and synchronized activities
+        /// </summary>
+        /// <param name="allianceId">Alliance coordinating event</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="eventType">Type of event to coordinate</param>
+        /// <param name="eventDetails">Event configuration and timing</param>
+        /// <param name="organizingPlayerId">Player organizing event</param>
+        /// <returns>Event coordination result with participant tracking</returns>
+        Task<(bool Success, string EventId, Dictionary<string, object> ParticipantTracking, DateTime EventStartTime)>
+            CoordinateAllianceEventAsync(int allianceId, int kingdomId, string eventType,
+                Dictionary<string, object> eventDetails, int organizingPlayerId);
+
+        /// <summary>
+        /// Processes coordinate sharing and strategic intelligence distribution
+        /// </summary>
+        /// <param name="allianceId">Alliance sharing intelligence</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="intelligenceType">Type of intelligence being shared</param>
+        /// <param name="intelligenceData">Intelligence data and coordinates</param>
+        /// <param name="sharingPlayerId">Player sharing intelligence</param>
+        /// <returns>Intelligence sharing result with distribution tracking</returns>
+        Task<Dictionary<string, object>> ProcessIntelligenceSharingAsync(int allianceId, int kingdomId,
+            string intelligenceType, Dictionary<string, object> intelligenceData, int sharingPlayerId);
+
+        #endregion
+
+        #region Alliance Progression & Leveling
+
+        /// <summary>
+        /// Processes alliance experience gains and level advancement with capacity/feature unlocks
+        /// </summary>
+        /// <param name="allianceId">Alliance gaining experience</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="experienceGained">Alliance experience points to add</param>
+        /// <param name="experienceSource">Source of experience for tracking</param>
+        /// <returns>Alliance level advancement result with unlocked features and capacity increases</returns>
+        Task<(bool LevelUp, int NewLevel, Dictionary<string, object> UnlockedFeatures,
+               Dictionary<string, int> CapacityIncreases)>
+            ProcessAllianceExperienceAsync(int allianceId, int kingdomId, long experienceGained, string experienceSource);
+
+        /// <summary>
+        /// Calculates alliance power rating based on member contributions, research, and territory
+        /// </summary>
+        /// <param name="allianceId">Alliance to calculate power for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Alliance power calculation with detailed breakdown</returns>
+        Task<(long TotalPower, Dictionary<string, long> PowerBreakdown)> CalculateAlliancePowerAsync(int allianceId,
+            int kingdomId);
+
+        /// <summary>
+        /// Manages alliance achievements and milestone rewards
+        /// </summary>
+        /// <param name="allianceId">Alliance processing achievements</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="achievementType">Type of achievement unlocked</param>
+        /// <param name="achievementData">Achievement progress and context</param>
+        /// <returns>Achievement processing result with rewards and recognition</returns>
+        Task<(bool NewAchievement, List<string> UnlockedAchievements, Dictionary<string, object> Rewards)>
+            ProcessAllianceAchievementAsync(int allianceId, int kingdomId, string achievementType,
+                Dictionary<string, object> achievementData);
+
+        #endregion
+
+        #region KvK Event Integration
+
+        /// <summary>
+        /// Integrates alliance into Kingdom vs Kingdom events while preserving alliance identity
+        /// </summary>
+        /// <param name="allianceId">Alliance participating in KvK</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="kvkEventId">KvK event identifier</param>
+        /// <param name="participationLevel">Level of alliance participation</param>
+        /// <returns>KvK integration result with role assignments and objectives</returns>
+        Task<(bool Success, Dictionary<string, object> RoleAssignments, Dictionary<string, object> Objectives,
+               Dictionary<string, object> RewardStructure)>
+            IntegrateKvKParticipationAsync(int allianceId, int kingdomId, string kvkEventId, string participationLevel);
+
+        /// <summary>
+        /// Coordinates multi-alliance operations during KvK events through coalition system
+        /// </summary>
+        /// <param name="coalitionId">Coalition coordinating KvK operations</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationType">Type of coordinated operation</param>
+        /// <param name="operationDetails">Operation parameters and objectives</param>
+        /// <returns>Multi-alliance coordination result with individual alliance contributions</returns>
+        Task<Dictionary<string, object>> CoordinateKvKOperationsAsync(string coalitionId, int kingdomId,
+            string operationType, Dictionary<string, object> operationDetails);
+
+        #endregion
+
+        #region Anti-Exploitation & Balance
+
+        /// <summary>
+        /// Monitors alliance activities for exploitation attempts and maintains balanced progression
+        /// </summary>
+        /// <param name="allianceId">Alliance to monitor</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="monitoringPeriodDays">Period to analyze for suspicious activity</param>
+        /// <returns>Monitoring result with risk assessment and recommended actions</returns>
+        Task<(bool SuspiciousActivity, List<string> RiskFactors, Dictionary<string, object> RecommendedActions)>
+            MonitorAllianceExploitationAsync(int allianceId, int kingdomId, int monitoringPeriodDays = 7);
+
+        /// <summary>
+        /// Validates alliance operations for fairness and prevents system gaming
+        /// </summary>
+        /// <param name="allianceId">Alliance performing operation</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationType">Type of operation being validated</param>
+        /// <param name="operationDetails">Operation parameters for validation</param>
+        /// <returns>Validation result with fairness assessment and restrictions</returns>
+        Task<(bool IsValid, List<string> ValidationWarnings, Dictionary<string, object> AppliedRestrictions)>
+            ValidateAllianceOperationAsync(int allianceId, int kingdomId, string operationType,
+                Dictionary<string, object> operationDetails);
+
+        /// <summary>
+        /// Ensures skill-based alternatives exist for premium alliance features
+        /// </summary>
+        /// <param name="allianceId">Alliance accessing features</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="featureType">Premium feature being accessed</param>
+        /// <returns>Skill-based alternatives and balance validation</returns>
+        Task<Dictionary<string, object>> ValidateSkillBasedAlternativesAsync(int allianceId, int kingdomId,
+            string featureType);
+
+        #endregion
+
+        #region Alliance Information & Analytics
+
+        /// <summary>
+        /// Retrieves comprehensive alliance profile including stats, members, and progression
+        /// </summary>
+        /// <param name="allianceId">Alliance to get profile for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="includePrivateData">Whether to include internal alliance data</param>
+        /// <param name="requestingPlayerId">Player requesting profile</param>
+        /// <returns>Alliance profile with appropriate data visibility</returns>
+        Task<Dictionary<string, object>> GetAllianceProfileAsync(int allianceId, int kingdomId,
+            bool includePrivateData = false, int? requestingPlayerId = null);
+
+        /// <summary>
+        /// Retrieves alliance rankings across different categories within kingdom
+        /// </summary>
+        /// <param name="allianceId">Alliance to get rankings for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Alliance rankings in power, members, research, territory, etc.</returns>
+        Task<Dictionary<string, object>> GetAllianceRankingsAsync(int allianceId, int kingdomId);
+
+        /// <summary>
+        /// Analyzes alliance performance metrics and provides improvement recommendations
+        /// </summary>
+        /// <param name="allianceId">Alliance to analyze</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="analysisType">Type of analysis to perform</param>
+        /// <param name="timeframeDays">Period to analyze</param>
+        /// <returns>Performance analysis with metrics and recommendations</returns>
+        Task<Dictionary<string, object>> AnalyzeAlliancePerformanceAsync(int allianceId, int kingdomId,
+            string analysisType, int timeframeDays = 30);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Services/ICombatService.cs

@@ -0,0 +1,396 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\ICombatService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Combat service interface for coordinating field interception system, battle resolution, march mechanics, and dragon integration - implements Shadowed Realms' core innovation of defenders meeting attackers before castle sieges
+ * Last Edit Notes: Initial creation with comprehensive combat system operations including field interception, anti-pay-to-win balance, and skill-based mechanics
+ */
+
+using ShadowedRealms.Core.Models;
+
+namespace ShadowedRealms.Core.Interfaces.Services
+{
+    /// <summary>
+    /// Service interface for combat-related business logic operations
+    /// Implements field interception system (core innovation), battle resolution, march mechanics, and anti-pay-to-win combat balance
+    /// </summary>
+    public interface ICombatService
+    {
+        #region Field Interception System (Core Innovation)
+
+        /// <summary>
+        /// Calculates interception opportunities for defenders against attacking marches
+        /// Core innovation: Defenders can meet attackers in the field before castle sieges
+        /// </summary>
+        /// <param name="attackingPlayerId">Player launching the attack</param>
+        /// <param name="defendingPlayerId">Player being attacked</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="attackRoute">Route details of the attacking march</param>
+        /// <returns>Interception calculations and opportunities</returns>
+        Task<Dictionary<string, object>> CalculateInterceptionOpportunitiesAsync(
+            int attackingPlayerId, int defendingPlayerId, int kingdomId, Dictionary<string, object> attackRoute);
+
+        /// <summary>
+        /// Executes field interception when defender chooses to meet attacker in the field
+        /// </summary>
+        /// <param name="defendingPlayerId">Player executing the interception</param>
+        /// <param name="attackingPlayerId">Player being intercepted</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="interceptionPoint">Coordinates where interception occurs</param>
+        /// <param name="defenderTroops">Troops sent by defender for interception</param>
+        /// <returns>Interception execution result and combat initiation</returns>
+        /// <exception cref="InvalidOperationException">Thrown when interception conditions not met</exception>
+        Task<(bool Success, Dictionary<string, object> BattleSetup, DateTime BattleStartTime)>
+            ExecuteFieldInterceptionAsync(int defendingPlayerId, int attackingPlayerId, int kingdomId,
+                (int X, int Y) interceptionPoint, Dictionary<string, int> defenderTroops);
+
+        /// <summary>
+        /// Validates field interception attempt with timing, distance, and troop availability checks
+        /// </summary>
+        /// <param name="defendingPlayerId">Player attempting interception</param>
+        /// <param name="attackingPlayerId">Player being intercepted</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="interceptionPoint">Proposed interception coordinates</param>
+        /// <returns>Validation result with detailed requirements and restrictions</returns>
+        Task<(bool CanIntercept, List<string> Requirements, Dictionary<string, object> Timing, List<string> Restrictions)>
+            ValidateFieldInterceptionAsync(int defendingPlayerId, int attackingPlayerId, int kingdomId,
+                (int X, int Y) interceptionPoint);
+
+        /// <summary>
+        /// Calculates optimal interception routes and timing windows for defenders
+        /// </summary>
+        /// <param name="defendingPlayerId">Player planning interception</param>
+        /// <param name="attackRoute">Attacking march route information</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Route optimization analysis with multiple interception options</returns>
+        Task<Dictionary<string, object>> CalculateOptimalInterceptionRoutesAsync(
+            int defendingPlayerId, Dictionary<string, object> attackRoute, int kingdomId);
+
+        #endregion
+
+        #region March Mechanics
+
+        /// <summary>
+        /// Initiates combat march with speed calculations, diminishing returns, and grace periods
+        /// </summary>
+        /// <param name="playerId">Player launching the march</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="targetCoordinates">Target destination coordinates</param>
+        /// <param name="troopComposition">Troops participating in march</param>
+        /// <param name="marchType">Type of march (attack, raid, siege, defense)</param>
+        /// <param name="dragonEquipped">Whether dragon accompanies the march</param>
+        /// <returns>March initiation result with timing and route details</returns>
+        /// <exception cref="InvalidOperationException">Thrown when march cannot be initiated</exception>
+        Task<(bool Success, string MarchId, DateTime EstimatedArrival, Dictionary<string, object> MarchDetails)>
+            InitiateCombatMarchAsync(int playerId, int kingdomId, (int X, int Y) targetCoordinates,
+                Dictionary<string, int> troopComposition, string marchType, bool dragonEquipped = false);
+
+        /// <summary>
+        /// Calculates march speed with diminishing returns for large armies and minimum march times
+        /// </summary>
+        /// <param name="troopComposition">Composition of marching troops</param>
+        /// <param name="distance">Distance to travel</param>
+        /// <param name="playerVipTier">Player's VIP tier for speed bonuses</param>
+        /// <param name="allianceResearchBonuses">Alliance research speed bonuses</param>
+        /// <param name="dragonSpeedBonus">Dragon-provided speed improvements</param>
+        /// <returns>Speed calculation with breakdown of contributing factors</returns>
+        Task<Dictionary<string, object>> CalculateMarchSpeedAsync(
+            Dictionary<string, int> troopComposition, double distance, int playerVipTier,
+            Dictionary<string, double> allianceResearchBonuses, double dragonSpeedBonus = 0.0);
+
+        /// <summary>
+        /// Processes march arrival and determines combat engagement or other outcomes
+        /// </summary>
+        /// <param name="marchId">Unique march identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Arrival processing result and next actions</returns>
+        Task<Dictionary<string, object>> ProcessMarchArrivalAsync(string marchId, int kingdomId);
+
+        /// <summary>
+        /// Cancels active march with appropriate penalties and troop return timing
+        /// </summary>
+        /// <param name="marchId">March to cancel</param>
+        /// <param name="playerId">Player cancelling march</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Cancellation result with penalties and return timing</returns>
+        Task<(bool Success, Dictionary<string, object> Penalties, DateTime TroopReturnTime)>
+            CancelMarchAsync(string marchId, int playerId, int kingdomId);
+
+        #endregion
+
+        #region Battle Resolution
+
+        /// <summary>
+        /// Executes complete battle resolution with statistical combat system
+        /// Balances attack/defense/health with damage modifiers and skill-based mechanics
+        /// </summary>
+        /// <param name="attackerId">Attacking player ID</param>
+        /// <param name="defenderId">Defending player ID</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="battleContext">Battle context including troops, location, buffs</param>
+        /// <returns>Complete battle results with casualties, victor, and rewards</returns>
+        Task<Dictionary<string, object>> ResolveBattleAsync(int attackerId, int defenderId, int kingdomId,
+            Dictionary<string, object> battleContext);
+
+        /// <summary>
+        /// Calculates pre-battle power comparison and estimated outcomes
+        /// </summary>
+        /// <param name="attackerTroops">Attacking army composition</param>
+        /// <param name="defenderTroops">Defending army composition</param>
+        /// <param name="battleModifiers">Combat modifiers from various sources</param>
+        /// <returns>Battle prediction analysis and probability outcomes</returns>
+        Task<Dictionary<string, object>> CalculateBattlePredictionAsync(
+            Dictionary<string, int> attackerTroops, Dictionary<string, int> defenderTroops,
+            Dictionary<string, object> battleModifiers);
+
+        /// <summary>
+        /// Processes battle casualties and survivor calculations with hospital mechanics
+        /// </summary>
+        /// <param name="battleResult">Complete battle outcome data</param>
+        /// <param name="attackerId">Attacking player ID</param>
+        /// <param name="defenderId">Defending player ID</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Casualty processing with wounded/killed breakdown</returns>
+        Task<Dictionary<string, object>> ProcessBattleCasualtiesAsync(
+            Dictionary<string, object> battleResult, int attackerId, int defenderId, int kingdomId);
+
+        /// <summary>
+        /// Applies battle rewards including experience, resources, and achievement progress
+        /// </summary>
+        /// <param name="winnerId">Victorious player ID</param>
+        /// <param name="loserId">Defeated player ID</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="battleResult">Complete battle outcome for reward calculations</param>
+        /// <returns>Rewards distributed to participants</returns>
+        Task<Dictionary<string, object>> ProcessBattleRewardsAsync(int winnerId, int loserId, int kingdomId,
+            Dictionary<string, object> battleResult);
+
+        #endregion
+
+        #region Dragon Integration
+
+        /// <summary>
+        /// Integrates dragon skills and equipment into combat calculations
+        /// Dragons must accompany armies and provide skill-based buffs rather than passive bonuses
+        /// </summary>
+        /// <param name="playerId">Player using dragon in combat</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="dragonSkills">Active dragon skills for this battle</param>
+        /// <param name="battleContext">Current battle context</param>
+        /// <returns>Dragon combat integration and skill effects</returns>
+        Task<Dictionary<string, object>> IntegrateDragonCombatAsync(int playerId, int kingdomId,
+            List<string> dragonSkills, Dictionary<string, object> battleContext);
+
+        /// <summary>
+        /// Validates dragon equipment and skill combinations for combat effectiveness
+        /// </summary>
+        /// <param name="playerId">Player's dragon setup</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="proposedSkills">Skills player wants to use</param>
+        /// <returns>Validation result with optimal skill recommendations</returns>
+        Task<(bool IsValid, List<string> ValidationErrors, Dictionary<string, object> OptimalSetup)>
+            ValidateDragonCombatSetupAsync(int playerId, int kingdomId, List<string> proposedSkills);
+
+        /// <summary>
+        /// Calculates dragon skill cooldowns and usage restrictions
+        /// </summary>
+        /// <param name="playerId">Player using dragon skills</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="skillsUsed">Skills activated in recent combat</param>
+        /// <returns>Cooldown timers and skill availability</returns>
+        Task<Dictionary<string, object>> CalculateDragonSkillCooldownsAsync(int playerId, int kingdomId,
+            List<string> skillsUsed);
+
+        #endregion
+
+        #region Attack Classification System
+
+        /// <summary>
+        /// Classifies attack type and applies appropriate speed/interception restrictions
+        /// Lightning raids (unrestricted) to castle sieges (fully restricted)
+        /// </summary>
+        /// <param name="attackerId">Player launching attack</param>
+        /// <param name="defenderId">Target player</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="attackParameters">Attack configuration parameters</param>
+        /// <returns>Attack classification with applicable restrictions and bonuses</returns>
+        Task<Dictionary<string, object>> ClassifyAttackTypeAsync(int attackerId, int defenderId, int kingdomId,
+            Dictionary<string, object> attackParameters);
+
+        /// <summary>
+        /// Validates attack restrictions based on classification and recent activity
+        /// </summary>
+        /// <param name="attackerId">Player attempting attack</param>
+        /// <param name="defenderId">Target player</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="attackType">Classified attack type</param>
+        /// <returns>Attack validation with restrictions and requirements</returns>
+        Task<(bool CanAttack, List<string> Restrictions, Dictionary<string, object> Requirements)>
+            ValidateAttackRestrictionsAsync(int attackerId, int defenderId, int kingdomId, string attackType);
+
+        #endregion
+
+        #region Stealth and Route Planning
+
+        /// <summary>
+        /// Provides free route planning tools vs premium convenience options
+        /// Maintains skill-based alternatives to premium features
+        /// </summary>
+        /// <param name="playerId">Player planning route</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="startCoordinates">Starting position</param>
+        /// <param name="targetCoordinates">Destination coordinates</param>
+        /// <param name="usePremiumTools">Whether to use premium route optimization</param>
+        /// <returns>Route planning analysis with free and premium options</returns>
+        Task<Dictionary<string, object>> CalculateRouteOptionsAsync(int playerId, int kingdomId,
+            (int X, int Y) startCoordinates, (int X, int Y) targetCoordinates, bool usePremiumTools = false);
+
+        /// <summary>
+        /// Calculates stealth mechanics and detection probabilities for marching armies
+        /// </summary>
+        /// <param name="marchingPlayerId">Player whose march may be detected</param>
+        /// <param name="observingPlayerId">Player who might detect the march</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="marchDetails">Details of the marching army</param>
+        /// <returns>Stealth calculation and detection probabilities</returns>
+        Task<Dictionary<string, object>> CalculateStealthMechanicsAsync(int marchingPlayerId, int observingPlayerId,
+            int kingdomId, Dictionary<string, object> marchDetails);
+
+        /// <summary>
+        /// Processes intelligence gathering and scouting reports
+        /// </summary>
+        /// <param name="scoutingPlayerId">Player conducting reconnaissance</param>
+        /// <param name="targetPlayerId">Player being scouted</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="scoutingMethod">Method used for intelligence gathering</param>
+        /// <returns>Intelligence report with accuracy based on scouting method</returns>
+        Task<Dictionary<string, object>> ProcessIntelligenceGatheringAsync(int scoutingPlayerId, int targetPlayerId,
+            int kingdomId, string scoutingMethod);
+
+        #endregion
+
+        #region Anti-Pay-to-Win Combat Balance
+
+        /// <summary>
+        /// Monitors combat outcomes for pay-to-win dominance and applies skill-based balance
+        /// Ensures free players can compete through strategic skill and coordination
+        /// </summary>
+        /// <param name="battleResult">Completed battle result</param>
+        /// <param name="attackerId">Attacking player ID</param>
+        /// <param name="defenderId">Defending player ID</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Balance analysis and any corrective measures needed</returns>
+        Task<Dictionary<string, object>> MonitorCombatBalanceAsync(Dictionary<string, object> battleResult,
+            int attackerId, int defenderId, int kingdomId);
+
+        /// <summary>
+        /// Calculates skill-based combat bonuses that provide alternatives to premium advantages
+        /// </summary>
+        /// <param name="playerId">Player to calculate skill bonuses for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="combatContext">Current combat situation</param>
+        /// <returns>Skill-based bonuses and strategic advantages</returns>
+        Task<Dictionary<string, object>> CalculateSkillBasedCombatBonusesAsync(int playerId, int kingdomId,
+            Dictionary<string, object> combatContext);
+
+        /// <summary>
+        /// Validates combat effectiveness ratios to ensure balanced gameplay
+        /// </summary>
+        /// <param name="playerId">Player to validate effectiveness for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="timeframeDays">Analysis timeframe in days</param>
+        /// <returns>Effectiveness analysis with balance recommendations</returns>
+        Task<Dictionary<string, object>> ValidateCombatEffectivenessAsync(int playerId, int kingdomId,
+            int timeframeDays = 30);
+
+        #endregion
+
+        #region Combat Statistics and Analytics
+
+        /// <summary>
+        /// Retrieves comprehensive combat history and performance analytics
+        /// </summary>
+        /// <param name="playerId">Player to get combat history for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="timeframeDays">Historical period to analyze</param>
+        /// <returns>Combat statistics and performance metrics</returns>
+        Task<Dictionary<string, object>> GetCombatHistoryAnalyticsAsync(int playerId, int kingdomId,
+            int timeframeDays = 30);
+
+        /// <summary>
+        /// Calculates kingdom-wide combat trends and power balance metrics
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to analyze</param>
+        /// <param name="analysisType">Type of analysis to perform</param>
+        /// <returns>Kingdom combat analytics and trend analysis</returns>
+        Task<Dictionary<string, object>> AnalyzeKingdomCombatTrendsAsync(int kingdomId, string analysisType);
+
+        /// <summary>
+        /// Generates battle replay data for post-combat analysis
+        /// </summary>
+        /// <param name="combatLogId">Combat log to generate replay for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Battle replay data and analysis points</returns>
+        Task<Dictionary<string, object>> GenerateBattleReplayAsync(int combatLogId, int kingdomId);
+
+        #endregion
+
+        #region Alliance Combat Coordination
+
+        /// <summary>
+        /// Coordinates alliance-wide combat operations and joint attacks
+        /// </summary>
+        /// <param name="coordinatingPlayerId">Player organizing alliance combat</param>
+        /// <param name="allianceId">Alliance conducting joint operations</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="operationDetails">Details of the coordinated operation</param>
+        /// <returns>Alliance combat coordination setup and timing</returns>
+        Task<Dictionary<string, object>> CoordinateAllianceCombatAsync(int coordinatingPlayerId, int allianceId,
+            int kingdomId, Dictionary<string, object> operationDetails);
+
+        /// <summary>
+        /// Processes alliance reinforcement requests and deployment
+        /// </summary>
+        /// <param name="requestingPlayerId">Player requesting reinforcements</param>
+        /// <param name="reinforcingPlayerId">Player providing reinforcements</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="reinforcementType">Type of reinforcement needed</param>
+        /// <returns>Reinforcement deployment result and timing</returns>
+        Task<(bool Success, DateTime ArrivalTime, Dictionary<string, object> ReinforcementDetails)>
+            ProcessAllianceReinforcementAsync(int requestingPlayerId, int reinforcingPlayerId, int kingdomId,
+                string reinforcementType);
+
+        #endregion
+
+        #region Combat Event Management
+
+        /// <summary>
+        /// Retrieves active combat events and march status for a player
+        /// </summary>
+        /// <param name="playerId">Player to check combat events for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Current combat events and active marches</returns>
+        Task<Dictionary<string, object>> GetActiveCombatEventsAsync(int playerId, int kingdomId);
+
+        /// <summary>
+        /// Processes scheduled combat events and automatic resolutions
+        /// </summary>
+        /// <param name="eventId">Combat event to process</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Event processing result and outcomes</returns>
+        Task<Dictionary<string, object>> ProcessScheduledCombatEventAsync(string eventId, int kingdomId);
+
+        /// <summary>
+        /// Cancels or modifies scheduled combat events when conditions change
+        /// </summary>
+        /// <param name="eventId">Combat event to modify</param>
+        /// <param name="playerId">Player making the modification</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="modificationType">Type of modification to apply</param>
+        /// <returns>Modification result and updated event details</returns>
+        Task<(bool Success, Dictionary<string, object> UpdatedEvent)> ModifyCombatEventAsync(
+            string eventId, int playerId, int kingdomId, string modificationType);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Services/IKingdomService.cs

@@ -0,0 +1,442 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IKingdomService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Kingdom service interface for coordinating kingdom-related business logic operations including KvK events, democratic leadership systems, population management, kingdom mergers, and multi-dimensional matchmaking systems
+ * Last Edit Notes: Initial creation with comprehensive kingdom management operations including democratic politics, KvK coordination, and population balance systems
+ */
+
+using ShadowedRealms.Core.Models;
+
+namespace ShadowedRealms.Core.Interfaces.Services
+{
+    /// <summary>
+    /// Service interface for kingdom-related business logic operations
+    /// Implements KvK events, democratic leadership systems, population management, and kingdom mergers with multi-dimensional analysis
+    /// </summary>
+    public interface IKingdomService
+    {
+        #region Kingdom vs Kingdom (KvK) Events
+
+        /// <summary>
+        /// Initiates Kingdom vs Kingdom event with multi-dimensional matchmaking analysis beyond raw power comparison
+        /// Includes alliance coalition coordination and democratic host selection processes
+        /// </summary>
+        /// <param name="initiatingKingdomId">Kingdom initiating the KvK event</param>
+        /// <param name="targetKingdomIds">Target kingdoms for KvK matchmaking</param>
+        /// <param name="kvkType">Type of KvK event (standard, championship, alliance_war)</param>
+        /// <param name="eventParameters">Event configuration and rules</param>
+        /// <returns>KvK initiation result with matchmaking analysis and event timeline</returns>
+        /// <exception cref="InvalidOperationException">Thrown when KvK requirements not met</exception>
+        Task<(bool Success, string KvKEventId, Dictionary<string, object> MatchmakingAnalysis, DateTime EventStartTime)>
+            InitiateKvKEventAsync(int initiatingKingdomId, List<int> targetKingdomIds, string kvkType,
+                Dictionary<string, object> eventParameters);
+
+        /// <summary>
+        /// Processes multi-dimensional matchmaking analysis for KvK events considering power, activity, alliance structure, and strategic balance
+        /// Goes beyond simple power comparison to ensure competitive and engaging matches
+        /// </summary>
+        /// <param name="kingdomIds">Kingdoms to analyze for matchmaking</param>
+        /// <param name="kvkType">Type of KvK event for appropriate balancing</param>
+        /// <param name="historicalData">Historical performance data for analysis</param>
+        /// <returns>Comprehensive matchmaking analysis with balance recommendations</returns>
+        Task<Dictionary<string, object>> ProcessMultiDimensionalMatchmakingAsync(List<int> kingdomIds, string kvkType,
+            Dictionary<string, object> historicalData);
+
+        /// <summary>
+        /// Coordinates KvK event execution with alliance coalition support and victory condition tracking
+        /// Supports multi-path success (Military/Economic/Diplomatic/Technology victories)
+        /// </summary>
+        /// <param name="kvkEventId">KvK event to coordinate</param>
+        /// <param name="participatingKingdoms">Kingdoms participating in event</param>
+        /// <param name="coalitionConfigurations">Alliance coalition setups for each kingdom</param>
+        /// <returns>KvK coordination result with participant tracking and victory progress</returns>
+        Task<Dictionary<string, object>> CoordinateKvKExecutionAsync(string kvkEventId,
+            List<int> participatingKingdoms, Dictionary<int, List<int>> coalitionConfigurations);
+
+        /// <summary>
+        /// Processes KvK event conclusion with victory determination and reward distribution
+        /// Supports multiple victory paths and calculates appropriate rewards for all participants
+        /// </summary>
+        /// <param name="kvkEventId">KvK event to conclude</param>
+        /// <param name="eventResults">Complete event results and statistics</param>
+        /// <returns>Event conclusion with victory analysis and reward distribution</returns>
+        Task<(bool Success, Dictionary<string, object> VictoryAnalysis, Dictionary<int, Dictionary<string, object>> KingdomRewards)>
+            ProcessKvKConclusionAsync(string kvkEventId, Dictionary<string, object> eventResults);
+
+        /// <summary>
+        /// Calculates and applies KvK season rankings and rewards based on performance across multiple events
+        /// </summary>
+        /// <param name="seasonId">KvK season to conclude</param>
+        /// <param name="kingdomIds">Kingdoms participating in season</param>
+        /// <returns>Season conclusion with rankings and seasonal rewards</returns>
+        Task<Dictionary<string, object>> ProcessKvKSeasonConclusionAsync(string seasonId, List<int> kingdomIds);
+
+        #endregion
+
+        #region Democratic Leadership Systems
+
+        /// <summary>
+        /// Conducts democratic election for kingdom leadership positions with transparent voting processes
+        /// Supports multiple leadership roles and ensures fair representation across alliances
+        /// </summary>
+        /// <param name="kingdomId">Kingdom conducting elections</param>
+        /// <param name="electionType">Type of election (king, council, kvk_host)</param>
+        /// <param name="candidateIds">Players eligible for leadership positions</param>
+        /// <param name="voterEligibility">Criteria for voting eligibility</param>
+        /// <returns>Election result with winner determination and vote transparency</returns>
+        Task<(bool Success, Dictionary<int, string> ElectedLeaders, Dictionary<string, object> ElectionResults,
+               Dictionary<string, object> VotingTransparency)>
+            ConductDemocraticElectionAsync(int kingdomId, string electionType, List<int> candidateIds,
+                Dictionary<string, object> voterEligibility);
+
+        /// <summary>
+        /// Manages democratic host selection for KvK events with alliance voting coordination
+        /// Ensures fair representation and prevents alliance monopolization of leadership
+        /// </summary>
+        /// <param name="kingdomId">Kingdom selecting KvK host</param>
+        /// <param name="kvkEventId">KvK event requiring host selection</param>
+        /// <param name="allianceVotes">Voting results from each alliance</param>
+        /// <param name="selectionCriteria">Criteria for host eligibility and selection</param>
+        /// <returns>Host selection result with democratic validation and authority grants</returns>
+        Task<(bool Success, int SelectedHostPlayerId, Dictionary<string, object> HostAuthorities,
+               Dictionary<string, object> SelectionValidation)>
+            ProcessDemocraticHostSelectionAsync(int kingdomId, string kvkEventId,
+                Dictionary<int, Dictionary<int, int>> allianceVotes, Dictionary<string, object> selectionCriteria);
+
+        /// <summary>
+        /// Implements democratic tax distribution system with transparent allocation and fair representation
+        /// Processes 4% resource tax from conquered kingdoms with royal distribution oversight
+        /// </summary>
+        /// <param name="distributingKingdomId">Kingdom distributing tax resources</param>
+        /// <param name="taxCollectionData">Tax resources collected from conquered territories</param>
+        /// <param name="distributionCriteria">Democratic criteria for resource allocation</param>
+        /// <param name="councilApproval">Council approval for distribution plan</param>
+        /// <returns>Tax distribution result with allocation transparency and recipient tracking</returns>
+        Task<(bool Success, Dictionary<string, object> DistributionPlan, Dictionary<int, Dictionary<string, long>> AllianceAllocations,
+               Dictionary<string, object> DistributionAudit)>
+            ProcessDemocraticTaxDistributionAsync(int distributingKingdomId, Dictionary<string, long> taxCollectionData,
+                Dictionary<string, object> distributionCriteria, Dictionary<int, bool> councilApproval);
+
+        /// <summary>
+        /// Manages royal council operations with democratic decision-making and transparent governance
+        /// </summary>
+        /// <param name="kingdomId">Kingdom managing council</param>
+        /// <param name="councilAction">Action being proposed or executed</param>
+        /// <param name="councilMembers">Current council membership</param>
+        /// <param name="actionDetails">Details of the proposed action</param>
+        /// <returns>Council action result with voting records and implementation plan</returns>
+        Task<(bool Success, Dictionary<string, object> ActionResult, Dictionary<int, bool> CouncilVotes,
+               Dictionary<string, object> ImplementationPlan)>
+            ManageRoyalCouncilActionAsync(int kingdomId, string councilAction, List<int> councilMembers,
+                Dictionary<string, object> actionDetails);
+
+        #endregion
+
+        #region Population Management
+
+        /// <summary>
+        /// Monitors kingdom population and triggers new kingdom creation when population exceeds capacity
+        /// Maintains optimal 1,200-1,500 player target per kingdom with automatic scaling
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to monitor population for</param>
+        /// <returns>Population monitoring result with capacity analysis and scaling recommendations</returns>
+        Task<Dictionary<string, object>> MonitorKingdomPopulationAsync(int kingdomId);
+
+        /// <summary>
+        /// Creates new kingdom when population thresholds are exceeded with smart player distribution
+        /// Ensures balanced player distribution and maintains competitive integrity
+        /// </summary>
+        /// <param name="originKingdomId">Kingdom triggering new kingdom creation</param>
+        /// <param name="newKingdomParameters">Parameters for new kingdom configuration</param>
+        /// <returns>New kingdom creation result with player distribution plan</returns>
+        Task<(bool Success, int NewKingdomId, Dictionary<string, object> KingdomConfiguration,
+               Dictionary<string, object> PlayerDistributionPlan)>
+            CreateNewKingdomAsync(int originKingdomId, Dictionary<string, object> newKingdomParameters);
+
+        /// <summary>
+        /// Processes player kingdom selection with smart defaults to newest kingdom
+        /// Balances player choice with population distribution needs
+        /// </summary>
+        /// <param name="playerId">Player selecting kingdom</param>
+        /// <param name="preferredKingdomId">Player's preferred kingdom (optional)</param>
+        /// <param name="selectionCriteria">Criteria for kingdom selection</param>
+        /// <returns>Kingdom selection result with placement reasoning and benefits</returns>
+        Task<(bool Success, int AssignedKingdomId, string PlacementReason, Dictionary<string, object> WelcomeBenefits)>
+            ProcessKingdomSelectionAsync(int playerId, int? preferredKingdomId, Dictionary<string, object> selectionCriteria);
+
+        /// <summary>
+        /// Manages kingdom population balance through voluntary migration incentives
+        /// Provides incentives for players to move to underpopulated kingdoms
+        /// </summary>
+        /// <param name="sourceKingdomId">Overpopulated source kingdom</param>
+        /// <param name="targetKingdomId">Underpopulated target kingdom</param>
+        /// <param name="migrationIncentives">Incentives offered for migration</param>
+        /// <returns>Migration management result with participant tracking and incentive distribution</returns>
+        Task<Dictionary<string, object>> ManagePopulationMigrationAsync(int sourceKingdomId, int targetKingdomId,
+            Dictionary<string, object> migrationIncentives);
+
+        /// <summary>
+        /// Calculates optimal kingdom capacity based on server performance and player engagement metrics
+        /// </summary>
+        /// <param name="serverId">Server to calculate capacity for</param>
+        /// <param name="performanceMetrics">Server performance data</param>
+        /// <param name="engagementMetrics">Player engagement analytics</param>
+        /// <returns>Capacity analysis with recommended kingdom limits and scaling strategies</returns>
+        Task<Dictionary<string, object>> CalculateOptimalKingdomCapacityAsync(int serverId,
+            Dictionary<string, object> performanceMetrics, Dictionary<string, object> engagementMetrics);
+
+        #endregion
+
+        #region Kingdom Mergers
+
+        /// <summary>
+        /// Processes voluntary kingdom merger with democratic approval and compatibility analysis
+        /// Ensures mergers maintain competitive balance and player satisfaction
+        /// </summary>
+        /// <param name="initiatingKingdomId">Kingdom proposing merger</param>
+        /// <param name="targetKingdomId">Kingdom being approached for merger</param>
+        /// <param name="mergerTerms">Proposed terms and conditions for merger</param>
+        /// <param name="compatibilityAnalysis">Analysis of kingdom compatibility</param>
+        /// <returns>Merger processing result with democratic validation and integration plan</returns>
+        /// <exception cref="InvalidOperationException">Thrown when merger requirements not met</exception>
+        Task<(bool Success, string MergerId, Dictionary<string, object> DemocraticValidation,
+               Dictionary<string, object> IntegrationPlan, DateTime MergerCompletionTime)>
+            ProcessKingdomMergerAsync(int initiatingKingdomId, int targetKingdomId, Dictionary<string, object> mergerTerms,
+                Dictionary<string, object> compatibilityAnalysis);
+
+        /// <summary>
+        /// Conducts democratic voting for kingdom merger approval with transparent processes
+        /// Requires approval from both kingdoms with appropriate quorum requirements
+        /// </summary>
+        /// <param name="mergerId">Merger proposal to vote on</param>
+        /// <param name="initiatingKingdomVotes">Votes from initiating kingdom</param>
+        /// <param name="targetKingdomVotes">Votes from target kingdom</param>
+        /// <param name="votingParameters">Parameters for voting validation</param>
+        /// <returns>Merger voting result with approval status and implementation timeline</returns>
+        Task<(bool MergerApproved, double InitiatingKingdomApproval, double TargetKingdomApproval,
+               Dictionary<string, object> VotingAnalysis, DateTime ImplementationDeadline)>
+            ProcessMergerVotingAsync(string mergerId, Dictionary<int, bool> initiatingKingdomVotes,
+                Dictionary<int, bool> targetKingdomVotes, Dictionary<string, object> votingParameters);
+
+        /// <summary>
+        /// Executes kingdom merger with player integration, alliance consolidation, and benefit preservation
+        /// Maintains competitive balance while combining kingdom resources and populations
+        /// </summary>
+        /// <param name="mergerId">Approved merger to execute</param>
+        /// <param name="mergerConfiguration">Configuration for merger execution</param>
+        /// <returns>Merger execution result with integration tracking and combined kingdom details</returns>
+        Task<(bool Success, int MergedKingdomId, Dictionary<string, object> IntegrationResults,
+               Dictionary<string, object> CombinedKingdomStatistics)>
+            ExecuteKingdomMergerAsync(string mergerId, Dictionary<string, object> mergerConfiguration);
+
+        /// <summary>
+        /// Analyzes kingdom compatibility for potential mergers considering population, power balance, and cultural fit
+        /// </summary>
+        /// <param name="kingdomId1">First kingdom for compatibility analysis</param>
+        /// <param name="kingdomId2">Second kingdom for compatibility analysis</param>
+        /// <returns>Compatibility analysis with merger viability assessment and recommendations</returns>
+        Task<Dictionary<string, object>> AnalyzeKingdomCompatibilityAsync(int kingdomId1, int kingdomId2);
+
+        #endregion
+
+        #region Teleportation Management
+
+        /// <summary>
+        /// Manages kingdom-wide teleportation restrictions and policies with balanced limitations
+        /// Implements proximity blocks, escalating costs, and anti-exploitation measures
+        /// </summary>
+        /// <param name="kingdomId">Kingdom managing teleportation</param>
+        /// <param name="teleportationPolicy">Policy configuration for teleportation rules</param>
+        /// <returns>Teleportation policy result with enforcement mechanisms and player impact analysis</returns>
+        Task<Dictionary<string, object>> ManageTeleportationRestrictionsAsync(int kingdomId,
+            Dictionary<string, object> teleportationPolicy);
+
+        /// <summary>
+        /// Processes mass teleportation events during kingdom events or emergencies
+        /// Coordinates large-scale player movement while maintaining game balance
+        /// </summary>
+        /// <param name="kingdomId">Kingdom processing mass teleportation</param>
+        /// <param name="teleportationEvent">Event triggering mass teleportation</param>
+        /// <param name="participantIds">Players participating in mass teleportation</param>
+        /// <param name="destinationParameters">Destination configuration and restrictions</param>
+        /// <returns>Mass teleportation result with success tracking and balance enforcement</returns>
+        Task<(bool Success, Dictionary<int, (int X, int Y)> PlayerDestinations, Dictionary<string, object> EventResults)>
+            ProcessMassTeleportationEventAsync(int kingdomId, string teleportationEvent, List<int> participantIds,
+                Dictionary<string, object> destinationParameters);
+
+        /// <summary>
+        /// Calculates optimal teleportation cost scaling to prevent exploitation while maintaining accessibility
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to calculate costs for</param>
+        /// <param name="teleportationData">Historical teleportation usage data</param>
+        /// <returns>Cost scaling analysis with recommended pricing and accessibility balance</returns>
+        Task<Dictionary<string, object>> CalculateTeleportationCostScalingAsync(int kingdomId,
+            Dictionary<string, object> teleportationData);
+
+        #endregion
+
+        #region Kingdom Analytics & Intelligence
+
+        /// <summary>
+        /// Generates comprehensive kingdom statistics and performance analytics
+        /// Provides insights for leadership decision-making and strategic planning
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to analyze</param>
+        /// <param name="analysisType">Type of analysis to perform</param>
+        /// <param name="timeframeDays">Period to analyze</param>
+        /// <returns>Comprehensive kingdom analytics with performance metrics and trend analysis</returns>
+        Task<Dictionary<string, object>> GenerateKingdomAnalyticsAsync(int kingdomId, string analysisType,
+            int timeframeDays = 30);
+
+        /// <summary>
+        /// Processes kingdom-wide intelligence gathering and threat assessment
+        /// Monitors external threats, internal stability, and strategic opportunities
+        /// </summary>
+        /// <param name="kingdomId">Kingdom conducting intelligence analysis</param>
+        /// <param name="intelligenceScope">Scope of intelligence gathering</param>
+        /// <param name="targetKingdoms">Target kingdoms for intelligence (optional)</param>
+        /// <returns>Intelligence analysis with threat assessment and strategic recommendations</returns>
+        Task<Dictionary<string, object>> ProcessKingdomIntelligenceAsync(int kingdomId, string intelligenceScope,
+            List<int> targetKingdoms = null);
+
+        /// <summary>
+        /// Monitors kingdom health metrics including player satisfaction, engagement, and retention
+        /// Provides early warning systems for kingdom stability issues
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to monitor health for</param>
+        /// <returns>Kingdom health analysis with stability indicators and improvement recommendations</returns>
+        Task<Dictionary<string, object>> MonitorKingdomHealthAsync(int kingdomId);
+
+        /// <summary>
+        /// Generates kingdom power rankings and comparative analysis against other kingdoms
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to rank</param>
+        /// <param name="comparisonKingdoms">Other kingdoms for comparative analysis</param>
+        /// <param name="rankingCriteria">Criteria for ranking calculation</param>
+        /// <returns>Kingdom ranking analysis with comparative metrics and positioning recommendations</returns>
+        Task<Dictionary<string, object>> GenerateKingdomRankingsAsync(int kingdomId, List<int> comparisonKingdoms,
+            Dictionary<string, object> rankingCriteria);
+
+        #endregion
+
+        #region Kingdom Events & Campaigns
+
+        /// <summary>
+        /// Manages kingdom-wide events and campaigns with participation tracking and reward distribution
+        /// Coordinates events that span multiple alliances and promote kingdom unity
+        /// </summary>
+        /// <param name="kingdomId">Kingdom hosting event</param>
+        /// <param name="eventType">Type of kingdom event</param>
+        /// <param name="eventConfiguration">Event setup and rules</param>
+        /// <param name="participationCriteria">Criteria for event participation</param>
+        /// <returns>Kingdom event result with participation tracking and reward distribution</returns>
+        Task<(bool Success, string EventId, Dictionary<string, object> ParticipationTracking,
+               Dictionary<string, object> RewardDistribution)>
+            ManageKingdomEventAsync(int kingdomId, string eventType, Dictionary<string, object> eventConfiguration,
+                Dictionary<string, object> participationCriteria);
+
+        /// <summary>
+        /// Processes kingdom-wide campaigns that require coordinated effort across multiple alliances
+        /// Manages complex objectives and promotes inter-alliance cooperation
+        /// </summary>
+        /// <param name="kingdomId">Kingdom conducting campaign</param>
+        /// <param name="campaignType">Type of campaign to execute</param>
+        /// <param name="campaignObjectives">Campaign goals and success criteria</param>
+        /// <param name="allianceParticipation">Alliance participation and coordination</param>
+        /// <returns>Campaign processing result with progress tracking and alliance coordination</returns>
+        Task<Dictionary<string, object>> ProcessKingdomCampaignAsync(int kingdomId, string campaignType,
+            Dictionary<string, object> campaignObjectives, Dictionary<int, Dictionary<string, object>> allianceParticipation);
+
+        /// <summary>
+        /// Coordinates seasonal kingdom competitions with balanced rewards and fair participation
+        /// </summary>
+        /// <param name="kingdomIds">Kingdoms participating in seasonal competition</param>
+        /// <param name="seasonType">Type of seasonal competition</param>
+        /// <param name="competitionRules">Rules and regulations for competition</param>
+        /// <returns>Seasonal competition coordination with fairness validation and reward structure</returns>
+        Task<Dictionary<string, object>> CoordinateSeasonalCompetitionAsync(List<int> kingdomIds, string seasonType,
+            Dictionary<string, object> competitionRules);
+
+        #endregion
+
+        #region Diplomatic Relations
+
+        /// <summary>
+        /// Manages inter-kingdom diplomatic relations including treaties, trade agreements, and conflict resolution
+        /// Facilitates peaceful resolution of conflicts and promotes strategic alliances
+        /// </summary>
+        /// <param name="kingdomId1">First kingdom in diplomatic relation</param>
+        /// <param name="kingdomId2">Second kingdom in diplomatic relation</param>
+        /// <param name="diplomaticAction">Type of diplomatic action</param>
+        /// <param name="actionDetails">Details and terms of diplomatic action</param>
+        /// <returns>Diplomatic action result with relation status and implementation timeline</returns>
+        Task<(bool Success, string DiplomaticStatus, Dictionary<string, object> RelationDetails,
+               DateTime ImplementationDeadline)>
+            ManageDiplomaticRelationsAsync(int kingdomId1, int kingdomId2, string diplomaticAction,
+                Dictionary<string, object> actionDetails);
+
+        /// <summary>
+        /// Processes inter-kingdom trade agreements and resource exchange programs
+        /// Promotes economic cooperation and balanced resource distribution
+        /// </summary>
+        /// <param name="exportingKingdomId">Kingdom exporting resources</param>
+        /// <param name="importingKingdomId">Kingdom importing resources</param>
+        /// <param name="tradeTerms">Terms and conditions for trade agreement</param>
+        /// <param name="tradeVolume">Volume and schedule of resource exchange</param>
+        /// <returns>Trade agreement result with exchange tracking and economic impact</returns>
+        Task<(bool Success, string TradeAgreementId, Dictionary<string, object> ExchangeSchedule,
+               Dictionary<string, object> EconomicImpactAnalysis)>
+            ProcessInterKingdomTradeAsync(int exportingKingdomId, int importingKingdomId,
+                Dictionary<string, object> tradeTerms, Dictionary<string, long> tradeVolume);
+
+        /// <summary>
+        /// Mediates kingdom conflicts and facilitates peaceful resolution mechanisms
+        /// </summary>
+        /// <param name="conflictingKingdoms">Kingdoms involved in conflict</param>
+        /// <param name="conflictDetails">Nature and details of the conflict</param>
+        /// <param name="mediationParameters">Parameters for conflict resolution</param>
+        /// <returns>Conflict mediation result with resolution plan and peace terms</returns>
+        Task<Dictionary<string, object>> MediateKingdomConflictAsync(List<int> conflictingKingdoms,
+            Dictionary<string, object> conflictDetails, Dictionary<string, object> mediationParameters);
+
+        #endregion
+
+        #region Kingdom Information & Status
+
+        /// <summary>
+        /// Retrieves comprehensive kingdom information including statistics, leadership, and current status
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to get information for</param>
+        /// <param name="includePrivateData">Whether to include sensitive internal data</param>
+        /// <param name="requestingPlayerId">Player requesting information (for access control)</param>
+        /// <returns>Kingdom information with appropriate data visibility</returns>
+        Task<Dictionary<string, object>> GetKingdomInformationAsync(int kingdomId, bool includePrivateData = false,
+            int? requestingPlayerId = null);
+
+        /// <summary>
+        /// Gets current kingdom status including active events, leadership, population, and stability indicators
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to get status for</param>
+        /// <returns>Current kingdom status with all active systems and indicators</returns>
+        Task<Dictionary<string, object>> GetKingdomStatusAsync(int kingdomId);
+
+        /// <summary>
+        /// Retrieves kingdom leaderboards and rankings across various categories
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to get rankings for</param>
+        /// <param name="rankingCategories">Categories to include in rankings</param>
+        /// <returns>Kingdom rankings across requested categories</returns>
+        Task<Dictionary<string, object>> GetKingdomRankingsAsync(int kingdomId, List<string> rankingCategories);
+
+        /// <summary>
+        /// Gets kingdom activity summary including recent events, battles, and significant changes
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to get activity summary for</param>
+        /// <param name="timeframeDays">Period to summarize activity for</param>
+        /// <returns>Kingdom activity summary with timeline of significant events</returns>
+        Task<Dictionary<string, object>> GetKingdomActivitySummaryAsync(int kingdomId, int timeframeDays = 7);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Services/IPlayerService.cs

@@ -0,0 +1,293 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IPlayerService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Player service interface for coordinating player-related business logic operations including castle progression, VIP management, teleportation mechanics, and cross-system player interactions
+ * Last Edit Notes: Initial creation with comprehensive player management operations
+ */
+
+using ShadowedRealms.Core.Models;
+
+namespace ShadowedRealms.Core.Interfaces.Services
+{
+    /// <summary>
+    /// Service interface for player-related business logic operations
+    /// Coordinates repository operations for castle progression, VIP management, teleportation, and player interactions
+    /// </summary>
+    public interface IPlayerService
+    {
+        #region Castle Management
+
+        /// <summary>
+        /// Upgrades player's castle to next level with resource validation and progression benefits
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="useSpeedups">Whether to apply speedup items to complete instantly</param>
+        /// <returns>Upgrade result with new castle level and benefits granted</returns>
+        /// <exception cref="InvalidOperationException">Thrown when upgrade requirements not met</exception>
+        /// <exception cref="ArgumentException">Thrown when player not found or invalid kingdom</exception>
+        Task<(bool Success, int NewCastleLevel, Dictionary<string, object> BenefitsGranted)> UpgradeCastleAsync(
+            int playerId, int kingdomId, bool useSpeedups = false);
+
+        /// <summary>
+        /// Calculates castle upgrade requirements and validates player readiness
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Upgrade requirements and validation results</returns>
+        Task<Dictionary<string, object>> GetCastleUpgradeRequirementsAsync(int playerId, int kingdomId);
+
+        /// <summary>
+        /// Processes castle construction queue with timing and resource management
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="buildingType">Type of building to construct</param>
+        /// <param name="useSpeedups">Whether to apply speedup items</param>
+        /// <returns>Construction result with completion time</returns>
+        Task<(bool Success, DateTime CompletionTime, Dictionary<string, object> ResourcesConsumed)> StartConstructionAsync(
+            int playerId, int kingdomId, string buildingType, bool useSpeedups = false);
+
+        #endregion
+
+        #region VIP Management
+
+        /// <summary>
+        /// Processes VIP tier advancement with secret tier handling and chargeback protection
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseAmount">Purchase amount contributing to VIP progress</param>
+        /// <returns>VIP update result with tier changes and benefits</returns>
+        Task<(bool TierChanged, int NewTier, bool IsSecretTier, Dictionary<string, object> NewBenefits, bool ChargebackRisk)>
+            ProcessVipAdvancementAsync(int playerId, int kingdomId, decimal purchaseAmount);
+
+        /// <summary>
+        /// Grants VIP-specific benefits including speed bonuses and exclusive features
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="vipTier">VIP tier to apply benefits for</param>
+        /// <returns>Benefits granted and their values</returns>
+        Task<Dictionary<string, object>> GrantVipBenefitsAsync(int playerId, int kingdomId, int vipTier);
+
+        /// <summary>
+        /// Validates VIP privilege usage and prevents abuse
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="privilegeType">Type of VIP privilege being used</param>
+        /// <returns>Validation result and privilege details</returns>
+        Task<(bool CanUse, string Reason, Dictionary<string, object> PrivilegeDetails)> ValidateVipPrivilegeAsync(
+            int playerId, int kingdomId, string privilegeType);
+
+        #endregion
+
+        #region Teleportation System
+
+        /// <summary>
+        /// Processes player teleportation with distance calculations, restrictions, and costs
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="targetX">Target X coordinate</param>
+        /// <param name="targetY">Target Y coordinate</param>
+        /// <param name="teleportType">Type of teleportation (free, paid, alliance)</param>
+        /// <returns>Teleportation result with new coordinates and costs</returns>
+        /// <exception cref="InvalidOperationException">Thrown when teleportation blocked or invalid</exception>
+        Task<(bool Success, int NewX, int NewY, Dictionary<string, object> CostsApplied, DateTime NextTeleportAvailable)>
+            ExecuteTeleportationAsync(int playerId, int kingdomId, int targetX, int targetY, string teleportType);
+
+        /// <summary>
+        /// Validates teleportation attempt and calculates costs/restrictions
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="targetX">Target X coordinate</param>
+        /// <param name="targetY">Target Y coordinate</param>
+        /// <returns>Validation result with costs and restrictions</returns>
+        Task<(bool CanTeleport, string Reason, Dictionary<string, object> Costs, List<string> Restrictions)>
+            ValidateTeleportationAsync(int playerId, int kingdomId, int targetX, int targetY);
+
+        /// <summary>
+        /// Checks for teleportation blocks due to proximity to other players or recent combat
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="targetX">Target X coordinate</param>
+        /// <param name="targetY">Target Y coordinate</param>
+        /// <returns>Block status and details</returns>
+        Task<(bool IsBlocked, string BlockReason, List<(int BlockingPlayerId, string PlayerName, double Distance)> NearbyPlayers)>
+            CheckTeleportationBlocksAsync(int playerId, int kingdomId, int targetX, int targetY);
+
+        #endregion
+
+        #region Resource Management
+
+        /// <summary>
+        /// Manages player resource collection, production bonuses, and capacity limits
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Collection result with resources gained and new totals</returns>
+        Task<Dictionary<string, object>> CollectResourcesAsync(int playerId, int kingdomId);
+
+        /// <summary>
+        /// Processes resource spending with validation and anti-exploitation checks
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="resourceCosts">Resources to spend by type</param>
+        /// <param name="purpose">Purpose of spending for logging</param>
+        /// <returns>Spending result and new resource totals</returns>
+        Task<(bool Success, Dictionary<string, long> NewResourceTotals, string ValidationMessage)>
+            SpendResourcesAsync(int playerId, int kingdomId, Dictionary<string, long> resourceCosts, string purpose);
+
+        /// <summary>
+        /// Calculates resource production rates including bonuses from buildings, VIP, and alliance research
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Production rates by resource type and contributing factors</returns>
+        Task<Dictionary<string, object>> CalculateResourceProductionAsync(int playerId, int kingdomId);
+
+        #endregion
+
+        #region Player Progression
+
+        /// <summary>
+        /// Processes player experience gains and level advancement
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="experienceGained">Experience points to add</param>
+        /// <param name="source">Source of experience for tracking</param>
+        /// <returns>Level advancement result and rewards</returns>
+        Task<(bool LevelUp, int NewLevel, Dictionary<string, object> LevelRewards)>
+            ProcessExperienceGainAsync(int playerId, int kingdomId, long experienceGained, string source);
+
+        /// <summary>
+        /// Updates player power calculation based on troops, buildings, research, and equipment
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>New power calculation and breakdown</returns>
+        Task<(long NewPower, Dictionary<string, long> PowerBreakdown)> RecalculatePlayerPowerAsync(int playerId, int kingdomId);
+
+        /// <summary>
+        /// Processes player achievements and milestone rewards
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="achievementType">Type of achievement unlocked</param>
+        /// <param name="progressValue">Progress value for achievement</param>
+        /// <returns>Achievement unlock result and rewards</returns>
+        Task<(bool NewAchievement, List<string> UnlockedAchievements, Dictionary<string, object> Rewards)>
+            ProcessAchievementProgressAsync(int playerId, int kingdomId, string achievementType, long progressValue);
+
+        #endregion
+
+        #region Combat Integration
+
+        /// <summary>
+        /// Prepares player for combat participation with troop validation and march setup
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="troopComposition">Troops to march with</param>
+        /// <param name="marchType">Type of march (attack, defend, gather)</param>
+        /// <returns>March preparation result and estimated arrival time</returns>
+        Task<(bool CanMarch, Dictionary<string, object> MarchDetails, DateTime EstimatedArrival, List<string> Warnings)>
+            PrepareCombatMarchAsync(int playerId, int kingdomId, Dictionary<string, int> troopComposition, string marchType);
+
+        /// <summary>
+        /// Processes combat participation results and updates player statistics
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="combatResult">Results from combat engagement</param>
+        /// <returns>Player updates applied from combat</returns>
+        Task<Dictionary<string, object>> ProcessCombatResultsAsync(int playerId, int kingdomId, Dictionary<string, object> combatResult);
+
+        #endregion
+
+        #region Social Integration
+
+        /// <summary>
+        /// Processes alliance invitation or application for player
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="allianceId">Alliance to join</param>
+        /// <param name="isInvitation">Whether this is an invitation or application</param>
+        /// <returns>Join result and alliance integration details</returns>
+        Task<(bool Success, Dictionary<string, object> AllianceDetails, List<string> NewPrivileges)>
+            ProcessAllianceJoinAsync(int playerId, int kingdomId, int allianceId, bool isInvitation);
+
+        /// <summary>
+        /// Handles player leaving alliance with territory and benefit adjustments
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="reason">Reason for leaving (voluntary, kicked, disbanded)</param>
+        /// <returns>Leave result and benefit adjustments</returns>
+        Task<(bool Success, Dictionary<string, object> BenefitsLost, bool TerritoryEviction)>
+            ProcessAllianceLeaveAsync(int playerId, int kingdomId, string reason);
+
+        #endregion
+
+        #region Anti-Exploitation
+
+        /// <summary>
+        /// Validates player actions for potential exploitation or cheating
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="actionType">Type of action being performed</param>
+        /// <param name="actionDetails">Details of the action for validation</param>
+        /// <returns>Validation result and risk assessment</returns>
+        Task<(bool IsValid, List<string> Warnings, Dictionary<string, object> RiskFactors)>
+            ValidatePlayerActionAsync(int playerId, int kingdomId, string actionType, Dictionary<string, object> actionDetails);
+
+        /// <summary>
+        /// Monitors player progression patterns for artificial acceleration or bot activity
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Monitoring result and any flags raised</returns>
+        Task<(bool SuspiciousActivity, List<string> Flags, Dictionary<string, object> ProgressionMetrics)>
+            MonitorProgressionPatternsAsync(int playerId, int kingdomId);
+
+        #endregion
+
+        #region Player Information
+
+        /// <summary>
+        /// Retrieves comprehensive player profile including stats, progression, and social connections
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="includePrivateData">Whether to include private data (for own profile)</param>
+        /// <returns>Complete player profile data</returns>
+        Task<Dictionary<string, object>> GetPlayerProfileAsync(int playerId, int kingdomId, bool includePrivateData = false);
+
+        /// <summary>
+        /// Retrieves player's current status including online state, march status, and active buffs
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Current player status information</returns>
+        Task<Dictionary<string, object>> GetPlayerStatusAsync(int playerId, int kingdomId);
+
+        /// <summary>
+        /// Retrieves player leaderboard rankings across different categories
+        /// </summary>
+        /// <param name="playerId">Player identifier</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <returns>Player rankings in power, level, kills, etc.</returns>
+        Task<Dictionary<string, object>> GetPlayerRankingsAsync(int playerId, int kingdomId);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Services/IPurchaseService.cs

@@ -0,0 +1,420 @@
+/*
+ * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IPurchaseService.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Purchase service interface for coordinating monetization-related business logic operations including anti-pay-to-win monitoring, VIP progression management, spending balance validation, and skill-based alternative systems
+ * Last Edit Notes: Initial creation with comprehensive anti-pay-to-win and balanced monetization operations
+ */
+
+using ShadowedRealms.Core.Models;
+
+namespace ShadowedRealms.Core.Interfaces.Services
+{
+    /// <summary>
+    /// Service interface for purchase and monetization-related business logic operations
+    /// Implements anti-pay-to-win monitoring, balanced VIP progression, spending validation, and skill-based alternatives
+    /// </summary>
+    public interface IPurchaseService
+    {
+        #region Purchase Processing & Validation
+
+        /// <summary>
+        /// Processes player purchase with comprehensive validation, fraud detection, and balance monitoring
+        /// Ensures all purchases maintain game balance and provide genuine value to players
+        /// </summary>
+        /// <param name="playerId">Player making the purchase</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseDetails">Details of the purchase including items and amounts</param>
+        /// <param name="paymentMethod">Payment method and transaction details</param>
+        /// <returns>Purchase processing result with validation status and applied benefits</returns>
+        /// <exception cref="InvalidOperationException">Thrown when purchase validation fails</exception>
+        Task<(bool Success, string TransactionId, Dictionary<string, object> AppliedBenefits,
+               Dictionary<string, object> BalanceValidation)>
+            ProcessPurchaseAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails,
+                Dictionary<string, object> paymentMethod);
+
+        /// <summary>
+        /// Validates purchase for game balance impact and anti-pay-to-win compliance
+        /// Prevents purchases that would create unfair advantages or disrupt competitive balance
+        /// </summary>
+        /// <param name="playerId">Player attempting purchase</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseDetails">Details of intended purchase</param>
+        /// <returns>Purchase validation result with balance assessment and recommendations</returns>
+        Task<(bool IsValid, List<string> ValidationWarnings, Dictionary<string, object> BalanceImpact,
+               Dictionary<string, object> AlternativeOptions)>
+            ValidatePurchaseBalanceAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails);
+
+        /// <summary>
+        /// Processes purchase refunds and chargebacks with appropriate game state adjustments
+        /// Handles refund scenarios while maintaining game integrity and preventing abuse
+        /// </summary>
+        /// <param name="playerId">Player requesting refund</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="transactionId">Original transaction to refund</param>
+        /// <param name="refundReason">Reason for refund request</param>
+        /// <param name="refundType">Type of refund (voluntary, chargeback, dispute)</param>
+        /// <returns>Refund processing result with game state adjustments and fraud prevention measures</returns>
+        Task<(bool Success, Dictionary<string, object> StateAdjustments, Dictionary<string, object> FraudPrevention)>
+            ProcessRefundAsync(int playerId, int kingdomId, string transactionId, string refundReason, string refundType);
+
+        /// <summary>
+        /// Detects and prevents purchase fraud including account manipulation and payment abuse
+        /// </summary>
+        /// <param name="playerId">Player making purchase</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseDetails">Purchase details for fraud analysis</param>
+        /// <param name="paymentMethod">Payment method details for validation</param>
+        /// <returns>Fraud detection result with risk assessment and prevention measures</returns>
+        Task<(bool IsFraudulent, double RiskScore, List<string> FraudIndicators, Dictionary<string, object> PreventionMeasures)>
+            DetectPurchaseFraudAsync(int playerId, int kingdomId, Dictionary<string, object> purchaseDetails,
+                Dictionary<string, object> paymentMethod);
+
+        #endregion
+
+        #region Anti-Pay-to-Win Monitoring
+
+        /// <summary>
+        /// Monitors spending patterns for pay-to-win dominance and implements balance corrections
+        /// Ensures competitive integrity by preventing spending from overwhelming skill-based gameplay
+        /// </summary>
+        /// <param name="playerId">Player to monitor spending patterns for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="monitoringPeriod">Time period for spending analysis</param>
+        /// <returns>Spending monitoring result with dominance assessment and balance recommendations</returns>
+        Task<Dictionary<string, object>> MonitorPayToWinDominanceAsync(int playerId, int kingdomId,
+            TimeSpan monitoringPeriod);
+
+        /// <summary>
+        /// Calculates competitive effectiveness ratio ensuring free players can achieve 70% effectiveness through skill
+        /// Validates that skill-based play remains viable against spending advantages
+        /// </summary>
+        /// <param name="playerId">Player to analyze effectiveness for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="comparisonGroup">Group of players for comparative analysis</param>
+        /// <returns>Effectiveness analysis with skill vs spending breakdown and balance validation</returns>
+        Task<Dictionary<string, object>> CalculateCompetitiveEffectivenessAsync(int playerId, int kingdomId,
+            List<int> comparisonGroup);
+
+        /// <summary>
+        /// Implements dynamic balance adjustments to counter pay-to-win dominance
+        /// Applies skill-based bonuses and strategic advantages to maintain competitive balance
+        /// </summary>
+        /// <param name="affectedPlayers">Players requiring balance adjustments</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="balanceType">Type of balance adjustment needed</param>
+        /// <param name="adjustmentParameters">Parameters for balance calculations</param>
+        /// <returns>Balance adjustment result with applied compensations and effectiveness validation</returns>
+        Task<Dictionary<string, object>> ImplementBalanceAdjustmentsAsync(List<int> affectedPlayers, int kingdomId,
+            string balanceType, Dictionary<string, object> adjustmentParameters);
+
+        /// <summary>
+        /// Validates that less than 30% of victory outcomes are determined purely by spending
+        /// Monitors competitive integrity across different game modes and scenarios
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to analyze victory patterns for</param>
+        /// <param name="analysisTimeframe">Period to analyze victory outcomes</param>
+        /// <param name="gameMode">Specific game mode to analyze (optional)</param>
+        /// <returns>Victory outcome analysis with spending influence assessment and balance status</returns>
+        Task<Dictionary<string, object>> ValidateVictoryOutcomeBalanceAsync(int kingdomId, TimeSpan analysisTimeframe,
+            string gameMode = null);
+
+        #endregion
+
+        #region VIP System Management
+
+        /// <summary>
+        /// Manages VIP tier progression with secret tier handling and chargeback protection
+        /// Implements graduated benefits that provide value without creating unfair advantages
+        /// </summary>
+        /// <param name="playerId">Player to manage VIP progression for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseAmount">Purchase amount contributing to VIP progress</param>
+        /// <param name="purchaseType">Type of purchase for VIP calculation</param>
+        /// <returns>VIP progression result with tier updates, benefits, and chargeback risk assessment</returns>
+        Task<(bool TierAdvanced, int NewVipTier, bool IsSecretTier, Dictionary<string, object> NewBenefits,
+               double ChargebackRisk, Dictionary<string, object> SkillAlternatives)>
+            ManageVipProgressionAsync(int playerId, int kingdomId, decimal purchaseAmount, string purchaseType);
+
+        /// <summary>
+        /// Calculates VIP benefits with built-in skill-based alternatives for non-VIP players
+        /// Ensures VIP provides convenience and cosmetic benefits rather than gameplay advantages
+        /// </summary>
+        /// <param name="playerId">Player to calculate VIP benefits for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="vipTier">VIP tier to calculate benefits for</param>
+        /// <returns>VIP benefit calculation with skill-based alternatives and balance validation</returns>
+        Task<Dictionary<string, object>> CalculateVipBenefitsWithAlternativesAsync(int playerId, int kingdomId, int vipTier);
+
+        /// <summary>
+        /// Processes VIP benefit claims with validation and anti-abuse measures
+        /// Prevents exploitation of VIP systems while ensuring legitimate benefits are applied
+        /// </summary>
+        /// <param name="playerId">Player claiming VIP benefits</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="benefitType">Type of VIP benefit being claimed</param>
+        /// <param name="claimParameters">Parameters for benefit claim</param>
+        /// <returns>Benefit claim result with validation status and applied benefits</returns>
+        Task<(bool Success, Dictionary<string, object> AppliedBenefits, List<string> ValidationWarnings)>
+            ProcessVipBenefitClaimAsync(int playerId, int kingdomId, string benefitType,
+                Dictionary<string, object> claimParameters);
+
+        /// <summary>
+        /// Manages chargeback protection for VIP tiers with appropriate game state adjustments
+        /// Handles chargeback scenarios while maintaining VIP tier integrity
+        /// </summary>
+        /// <param name="playerId">Player with chargeback activity</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="chargebackDetails">Details of chargeback activity</param>
+        /// <returns>Chargeback handling result with tier adjustments and protection measures</returns>
+        Task<Dictionary<string, object>> HandleVipChargebackProtectionAsync(int playerId, int kingdomId,
+            Dictionary<string, object> chargebackDetails);
+
+        #endregion
+
+        #region Skill-Based Alternative Systems
+
+        /// <summary>
+        /// Provides skill-based alternatives to premium features ensuring competitive viability for free players
+        /// Implements achievement-based unlocks and strategic gameplay rewards
+        /// </summary>
+        /// <param name="playerId">Player to provide alternatives for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="premiumFeature">Premium feature to provide alternatives for</param>
+        /// <returns>Skill-based alternatives with achievement paths and strategic options</returns>
+        Task<Dictionary<string, object>> ProvideSkillBasedAlternativesAsync(int playerId, int kingdomId,
+            string premiumFeature);
+
+        /// <summary>
+        /// Calculates achievement-based rewards that provide competitive alternatives to spending
+        /// Ensures skilled gameplay is recognized and rewarded appropriately
+        /// </summary>
+        /// <param name="playerId">Player to calculate achievement rewards for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="achievementCategory">Category of achievements to analyze</param>
+        /// <param name="timeframeDays">Period to analyze achievements over</param>
+        /// <returns>Achievement-based rewards with competitive value assessment</returns>
+        Task<Dictionary<string, object>> CalculateAchievementBasedRewardsAsync(int playerId, int kingdomId,
+            string achievementCategory, int timeframeDays = 30);
+
+        /// <summary>
+        /// Implements strategic coordination bonuses that reward teamwork and skill over individual spending
+        /// Promotes alliance cooperation and tactical gameplay
+        /// </summary>
+        /// <param name="playerId">Player participating in strategic coordination</param>
+        /// <param name="allianceId">Alliance coordinating strategy</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="coordinationType">Type of strategic coordination</param>
+        /// <param name="participationData">Data on player participation and effectiveness</param>
+        /// <returns>Coordination bonuses with skill-based rewards and team effectiveness boosts</returns>
+        Task<Dictionary<string, object>> ImplementStrategicCoordinationBonusesAsync(int playerId, int allianceId,
+            int kingdomId, string coordinationType, Dictionary<string, object> participationData);
+
+        /// <summary>
+        /// Validates that skill-based alternatives provide meaningful competitive options
+        /// Ensures balance between premium convenience and skill-based achievement
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to validate alternatives for</param>
+        /// <param name="alternativeType">Type of skill-based alternative to validate</param>
+        /// <param name="validationCriteria">Criteria for alternative effectiveness</param>
+        /// <returns>Alternative validation with effectiveness assessment and improvement recommendations</returns>
+        Task<Dictionary<string, object>> ValidateSkillBasedAlternativeEffectivenessAsync(int kingdomId,
+            string alternativeType, Dictionary<string, object> validationCriteria);
+
+        #endregion
+
+        #region Spending Analytics & Insights
+
+        /// <summary>
+        /// Generates comprehensive spending analytics for player behavior analysis and balance monitoring
+        /// Provides insights for maintaining healthy monetization while preserving competitive integrity
+        /// </summary>
+        /// <param name="playerId">Player to analyze spending for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="analysisType">Type of spending analysis to perform</param>
+        /// <param name="timeframeDays">Period to analyze spending over</param>
+        /// <returns>Comprehensive spending analytics with behavior patterns and balance insights</returns>
+        Task<Dictionary<string, object>> GenerateSpendingAnalyticsAsync(int playerId, int kingdomId,
+            string analysisType, int timeframeDays = 30);
+
+        /// <summary>
+        /// Analyzes kingdom-wide spending patterns for balance monitoring and health assessment
+        /// Identifies spending concentration and competitive balance issues
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to analyze spending patterns for</param>
+        /// <param name="analysisDepth">Depth of analysis to perform</param>
+        /// <returns>Kingdom spending analysis with balance assessment and health indicators</returns>
+        Task<Dictionary<string, object>> AnalyzeKingdomSpendingPatternsAsync(int kingdomId, string analysisDepth);
+
+        /// <summary>
+        /// Calculates player lifetime value with ethical monetization considerations
+        /// Balances revenue optimization with player satisfaction and retention
+        /// </summary>
+        /// <param name="playerId">Player to calculate lifetime value for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="projectionMonths">Months to project lifetime value over</param>
+        /// <returns>Lifetime value calculation with ethical monetization recommendations</returns>
+        Task<Dictionary<string, object>> CalculatePlayerLifetimeValueAsync(int playerId, int kingdomId,
+            int projectionMonths = 12);
+
+        /// <summary>
+        /// Monitors monetization health metrics ensuring sustainable and ethical revenue generation
+        /// Tracks player satisfaction, retention, and competitive balance alongside revenue metrics
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to monitor monetization health for</param>
+        /// <param name="healthMetrics">Specific health metrics to analyze</param>
+        /// <returns>Monetization health assessment with sustainability recommendations</returns>
+        Task<Dictionary<string, object>> MonitorMonetizationHealthAsync(int kingdomId, List<string> healthMetrics);
+
+        #endregion
+
+        #region Purchase Recommendations & Optimization
+
+        /// <summary>
+        /// Provides ethical purchase recommendations that genuinely benefit players without creating unfair advantages
+        /// Focuses on convenience, cosmetic, and quality-of-life improvements
+        /// </summary>
+        /// <param name="playerId">Player to provide recommendations for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="playerPreferences">Player preferences and gameplay patterns</param>
+        /// <returns>Ethical purchase recommendations with genuine value assessment</returns>
+        Task<Dictionary<string, object>> ProvideEthicalPurchaseRecommendationsAsync(int playerId, int kingdomId,
+            Dictionary<string, object> playerPreferences);
+
+        /// <summary>
+        /// Optimizes purchase timing and value to maximize player satisfaction while maintaining balance
+        /// Prevents aggressive monetization tactics that could harm player experience
+        /// </summary>
+        /// <param name="playerId">Player to optimize purchases for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="purchaseHistory">Player's purchase history and patterns</param>
+        /// <returns>Purchase optimization with player-first recommendations and value maximization</returns>
+        Task<Dictionary<string, object>> OptimizePurchaseValueAsync(int playerId, int kingdomId,
+            Dictionary<string, object> purchaseHistory);
+
+        /// <summary>
+        /// Implements spending caps and healthy monetization limits to prevent excessive spending
+        /// Protects players from harmful spending patterns while maintaining business viability
+        /// </summary>
+        /// <param name="playerId">Player to manage spending limits for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="spendingData">Current spending patterns and history</param>
+        /// <param name="limitParameters">Parameters for spending limit calculation</param>
+        /// <returns>Spending limit management with player protection measures and healthy spending guidance</returns>
+        Task<(bool LimitsApplied, Dictionary<string, object> SpendingLimits, Dictionary<string, object> HealthGuidance)>
+            ManageHealthySpendingLimitsAsync(int playerId, int kingdomId, Dictionary<string, object> spendingData,
+                Dictionary<string, object> limitParameters);
+
+        #endregion
+
+        #region Transaction Security & Compliance
+
+        /// <summary>
+        /// Validates transaction security and compliance with platform requirements and regulations
+        /// Ensures all transactions meet legal and platform compliance standards
+        /// </summary>
+        /// <param name="transactionDetails">Details of transaction to validate</param>
+        /// <param name="complianceRequirements">Applicable compliance requirements</param>
+        /// <returns>Transaction compliance validation with security assessment and regulatory compliance status</returns>
+        Task<(bool IsCompliant, List<string> ComplianceIssues, Dictionary<string, object> SecurityAssessment)>
+            ValidateTransactionComplianceAsync(Dictionary<string, object> transactionDetails,
+                Dictionary<string, object> complianceRequirements);
+
+        /// <summary>
+        /// Processes payment security verification with fraud prevention and risk assessment
+        /// Implements comprehensive security measures to protect against payment fraud
+        /// </summary>
+        /// <param name="paymentDetails">Payment information to verify</param>
+        /// <param name="playerVerification">Player identity verification data</param>
+        /// <returns>Payment security verification with fraud risk assessment and verification status</returns>
+        Task<(bool IsSecure, double FraudRisk, Dictionary<string, object> SecurityChecks)>
+            VerifyPaymentSecurityAsync(Dictionary<string, object> paymentDetails,
+                Dictionary<string, object> playerVerification);
+
+        /// <summary>
+        /// Manages transaction audit trails for compliance and dispute resolution
+        /// Maintains comprehensive records for regulatory compliance and player protection
+        /// </summary>
+        /// <param name="transactionId">Transaction to create audit trail for</param>
+        /// <param name="auditDetails">Details to include in audit trail</param>
+        /// <returns>Audit trail creation result with compliance record and dispute prevention measures</returns>
+        Task<Dictionary<string, object>> CreateTransactionAuditTrailAsync(string transactionId,
+            Dictionary<string, object> auditDetails);
+
+        #endregion
+
+        #region Purchase History & Player Protection
+
+        /// <summary>
+        /// Retrieves comprehensive purchase history with privacy protection and dispute support
+        /// Provides transparent purchase records while protecting sensitive payment information
+        /// </summary>
+        /// <param name="playerId">Player to retrieve purchase history for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="timeframeDays">Period to retrieve history for</param>
+        /// <param name="includeDetails">Whether to include detailed transaction information</param>
+        /// <returns>Purchase history with privacy-protected details and dispute support information</returns>
+        Task<Dictionary<string, object>> GetPurchaseHistoryAsync(int playerId, int kingdomId, int timeframeDays = 90,
+            bool includeDetails = false);
+
+        /// <summary>
+        /// Provides purchase dispute resolution support with fair and transparent processes
+        /// Handles player concerns and disputes with appropriate resolution mechanisms
+        /// </summary>
+        /// <param name="playerId">Player raising dispute</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="disputeDetails">Details of the dispute</param>
+        /// <param name="disputeType">Type of dispute being raised</param>
+        /// <returns>Dispute resolution result with investigation findings and resolution actions</returns>
+        Task<(bool DisputeResolved, Dictionary<string, object> ResolutionActions, Dictionary<string, object> InvestigationFindings)>
+            ProcessPurchaseDisputeAsync(int playerId, int kingdomId, Dictionary<string, object> disputeDetails,
+                string disputeType);
+
+        /// <summary>
+        /// Implements player protection measures for vulnerable spending patterns
+        /// Identifies and supports players who may need protection from excessive spending
+        /// </summary>
+        /// <param name="playerId">Player to assess protection needs for</param>
+        /// <param name="kingdomId">Kingdom scope for security</param>
+        /// <param name="spendingPattern">Player's spending behavior and patterns</param>
+        /// <returns>Player protection assessment with support measures and intervention recommendations</returns>
+        Task<Dictionary<string, object>> AssessPlayerProtectionNeedsAsync(int playerId, int kingdomId,
+            Dictionary<string, object> spendingPattern);
+
+        #endregion
+
+        #region Revenue Analytics & Business Intelligence
+
+        /// <summary>
+        /// Generates ethical revenue analytics that balance business goals with player welfare
+        /// Provides insights for sustainable monetization strategies
+        /// </summary>
+        /// <param name="kingdomIds">Kingdoms to analyze revenue for</param>
+        /// <param name="analysisType">Type of revenue analysis to perform</param>
+        /// <param name="timeframeDays">Period to analyze revenue over</param>
+        /// <returns>Revenue analytics with ethical monetization insights and sustainability recommendations</returns>
+        Task<Dictionary<string, object>> GenerateEthicalRevenueAnalyticsAsync(List<int> kingdomIds, string analysisType,
+            int timeframeDays = 30);
+
+        /// <summary>
+        /// Analyzes purchase conversion patterns with player satisfaction correlation
+        /// Identifies conversion opportunities that genuinely benefit players
+        /// </summary>
+        /// <param name="kingdomId">Kingdom to analyze conversion patterns for</param>
+        /// <param name="conversionType">Type of conversion to analyze</param>
+        /// <returns>Conversion analysis with player satisfaction correlation and ethical improvement recommendations</returns>
+        Task<Dictionary<string, object>> AnalyzePurchaseConversionPatternsAsync(int kingdomId, string conversionType);
+
+        /// <summary>
+        /// Calculates sustainable monetization metrics that prioritize long-term player value
+        /// Balances revenue goals with player retention and satisfaction
+        /// </summary>
+        /// <param name="kingdomIds">Kingdoms to calculate metrics for</param>
+        /// <param name="sustainabilityFactors">Factors to consider in sustainability calculation</param>
+        /// <returns>Sustainable monetization metrics with long-term viability assessment</returns>
+        Task<Dictionary<string, object>> CalculateSustainableMonetizationMetricsAsync(List<int> kingdomIds,
+            Dictionary<string, object> sustainabilityFactors);
+
+        #endregion
+    }
+}