ThordekkCore/PHASE_3_INTEGRATION_ARCHITECTURE.md

Phase 3 System Integration Architecture

Date: 2025-11-10 Status: Integration Planning Complete - Implementation Pending Objective: Unify all Phase 3 economic systems (Profession, Gathering, Auction, Banking) into cohesive bot economy

---

Executive Summary

The PlayerBot module has 4 independent economic systems that currently operate in isolation:

1. ProfessionManager (SINGLETON) - Crafting, recipe learning, skill management
2. GatheringManager (BehaviorManager) - Node detection, resource harvesting
3. AuctionManager (BehaviorManager) - Market analysis, auction trading
4. BankingManager (MISSING - only GuildBankManager exists)

Integration Goal: Connect these systems so bots can:

• Gather materials → Craft items → Sell on Auction House → Store gold in bank
• Buy materials from AH → Craft for profit → Reinvest earnings
• Optimize profession leveling path based on market prices

---

1. Current Architecture Assessment

1.1 ProfessionManager (SINGLETON Pattern)

Status: ✅ PRODUCTION-READY (after orphaned null check removal) Pattern: Singleton (ProfessionManager::instance()) Thread Safety: ❌ NO (uses per-bot instance data maps, no BehaviorManager integration) Update Method: Called from BotAI::UpdateAI() line 3179

Capabilities:

// Profession Management
bool LearnProfession(Player* player, ProfessionType profession);
uint16 GetProfessionSkill(Player* player, ProfessionType profession);
std::vector<ProfessionSkillInfo> GetPlayerProfessions(Player* player);

// Recipe System
bool LearnRecipe(Player* player, uint32 recipeId);
bool KnowsRecipe(Player* player, uint32 recipeId);
std::vector<RecipeInfo> GetCraftableRecipes(Player* player, ProfessionType profession);
RecipeInfo const* GetOptimalLevelingRecipe(Player* player, ProfessionType profession);

// Crafting Automation
bool CraftItem(Player* player, RecipeInfo const& recipe, uint32 quantity);
void QueueCraft(Player* player, uint32 recipeId, uint32 quantity);
bool HasMaterialsForRecipe(Player* player, RecipeInfo const& recipe);
std::vector<std::pair<uint32, uint32>> GetMissingMaterials(Player* player, RecipeInfo const& recipe);

// Skill Analysis
float GetSkillUpChance(Player* player, RecipeInfo const& recipe);
bool ShouldCraftForSkillUp(Player* player, RecipeInfo const& recipe);

Integration Points:

• Used by FarmingCoordinator for skill tracking
• Used by ProfessionAuctionBridge for craft → sell pipeline (EXISTS but needs review)
• Called from BotAI::Update() for automation

Architecture Issue:

• SINGLETON pattern conflicts with BehaviorManager design pattern used everywhere else
• No throttling (called every update, not interval-based)
• No mutex protection for shared state

---

1.2 GatheringManager (BehaviorManager Pattern)

Status: ✅ PRODUCTION-READY Pattern: Extends BehaviorManager Thread Safety: ✅ YES (atomic state flags, lock-free spatial grids) Update Interval: 1000ms (1 second throttled updates)

Capabilities:

// Node Detection
std::vector<GatheringNode> ScanForNodes(float range = 40.0f);
GatheringNode const* FindNearestNode(GatheringNodeType nodeType = GatheringNodeType::NONE);
bool CanGatherFromNode(GatheringNode const& node);

// Gathering Actions
bool GatherFromNode(GatheringNode const& node);
bool CastGatheringSpell(GatheringNode const& node);
bool LootNode(GameObject* gameObject);
bool SkinCreature(Creature* creature);

// Pathfinding
bool PathToNode(GatheringNode const& node);
bool IsInGatheringRange(GatheringNode const& node);

// Configuration
void SetGatheringEnabled(bool enable);
void SetProfessionEnabled(GatheringNodeType nodeType, bool enable);
void SetPrioritizeSkillUps(bool prioritize);

// Statistics
GatheringStatistics const& GetStatistics();

Integration Points:

• Used by FarmingCoordinator for automated material collection
• Needs connection to ProfessionManager for "gather materials I need to craft" logic

Architecture Strength:

• Perfect BehaviorManager implementation
• Lock-free spatial grid queries (Phase 5F integration)
• Atomic state flags for fast queries

---

1.3 AuctionManager (BehaviorManager Pattern)

Status: ✅ PRODUCTION-READY (after orphaned null check removal) Pattern: Extends BehaviorManager Thread Safety: ✅ YES (std::recursive_mutex, AuctionEventBus) Update Interval: 5000ms (5 second throttled updates)

Capabilities:

// Market Analysis
MarketSnapshot AnalyzeMarket(Player* bot, uint32 itemId);
uint64 GetRecommendedSellPrice(Player* bot, uint32 itemId);
std::vector<FlipOpportunity> FindFlipOpportunities(Player* bot);

// Auction Actions
bool PostAuction(Player* bot, uint32 itemId, uint32 stackSize, uint64 buyout, uint64 bid, uint32 duration);
bool BidOnAuction(Player* bot, uint32 auctionId, uint64 bidAmount);
bool BuyoutAuction(Player* bot, uint32 auctionId);
bool CancelAuction(Player* bot, uint32 auctionId);

// Automation Strategies
void ExecuteFlippingStrategy(Player* bot);
void ExecuteCommodityStrategy(Player* bot);
void ExecuteUndercutStrategy(Player* bot);

// Configuration
void SetStrategyEnabled(TradingStrategy strategy, bool enabled);
void SetMinProfitMargin(float margin);
void SetMaxAuctionDuration(uint32 hours);

// Statistics
AuctionStatistics const& GetStatistics();

Integration Points:

• Used by ProfessionAuctionBridge for selling crafted items (EXISTS)
• Needs connection to ProfessionManager for "buy materials I need" logic
• Event-driven via AuctionEventBus (auction sold, auction bought, etc.)

Architecture Strength:

• Event-driven architecture (AuctionEventBus)
• 6 trading strategies (flipping, commodity, undercut, snipe, crafting, flip)
• Market analysis with price volatility tracking

---

1.4 BankingManager (MISSING)

Status: ❌ DOES NOT EXIST What Exists:

• GuildBankManager - Guild banking only
• InteractionManager::AccessBank() - Manual bank access

What's Needed:

// Personal Banking Automation (NEEDS IMPLEMENTATION)
class BankingManager : public BehaviorManager
{
    // Auto-deposit
    bool DepositGold(Player* bot, uint64 amount);
    bool DepositItem(Player* bot, Item* item);
    void AutoDepositJunk(Player* bot);
    void AutoDepositCraftingMaterials(Player* bot);

    // Auto-withdraw
    bool WithdrawGold(Player* bot, uint64 amount);
    bool WithdrawItem(Player* bot, uint32 itemId, uint32 quantity);
    std::vector<Item*> WithdrawCraftingMaterials(Player* bot, RecipeInfo const& recipe);

    // Configuration
    void SetAutoDepositEnabled(bool enable);
    void SetMinGoldToKeep(uint64 amount);  // Keep X gold in bags, bank the rest

    // Queries
    uint64 GetBankGold(Player* bot);
    uint32 GetBankItemCount(Player* bot, uint32 itemId);
};

Priority: MEDIUM (nice-to-have, not critical for Phase 3 integration)

---

2. Integration Bridges Required

2.1 ProfessionAuctionBridge (PARTIALLY EXISTS)

Status: EXISTS at /home/user/TrinityCore/src/modules/Playerbot/Professions/ProfessionAuctionBridge.cpp Needs: Code review and potential updates

Purpose: Connect crafting to auction selling

Current Implementation:

// EXISTS - Review needed
class ProfessionAuctionBridge
{
    std::vector<std::pair<uint32, uint32>> GetMissingMaterialsForRecipe(...);
    bool ShouldCraftItemForProfit(...);
    bool CalculateCraftingProfit(...);
};

Enhancement Needed: Auto-sell crafted items

---

2.2 GatheringMaterialsBridge (NEEDS IMPLEMENTATION)

Status: DOES NOT EXIST Purpose: Connect gathering to crafting material requirements

Proposed API:

class GatheringMaterialsBridge
{
public:
    /**
     * @brief Get materials needed for bot's current crafting queue
     * @param bot Player bot
     * @return Vector of (itemId, quantity) pairs needed
     */
    std::vector<std::pair<uint32, uint32>> GetNeededMaterials(Player* bot);

    /**
     * @brief Check if gathered item is useful for bot's professions
     * @param bot Player bot
     * @param itemId Item gathered
     * @return true if item is needed for known recipes
     */
    bool IsItemNeededForCrafting(Player* bot, uint32 itemId);

    /**
     * @brief Prioritize gathering nodes based on material needs
     * @param bot Player bot
     * @param nodes Available gathering nodes
     * @return Sorted nodes (highest priority first)
     */
    std::vector<GatheringNode> PrioritizeNodesByNeeds(
        Player* bot,
        std::vector<GatheringNode> const& nodes);

    /**
     * @brief Trigger gathering session for specific material
     * @param bot Player bot
     * @param itemId Material to gather
     * @param quantity Amount needed
     * @return true if gathering session started
     */
    bool StartGatheringForMaterial(Player* bot, uint32 itemId, uint32 quantity);
};

Integration Flow:

ProfessionManager::QueueCraft(recipeId, qty)
  → GetMissingMaterials(recipe)
    → GatheringMaterialsBridge::StartGatheringForMaterial(itemId, qty)
      → GatheringManager::SetPrioritizeSkillUps(false)  // Prioritize materials over skill-ups
      → GatheringManager::ScanForNodes()
      → GatheringMaterialsBridge::PrioritizeNodesByNeeds(nodes)
        → GatheringManager::GatherFromNode(prioritized_node)

---

2.3 AuctionMaterialsBridge (NEEDS IMPLEMENTATION)

Status: DOES NOT EXIST Purpose: Auto-buy materials from AH when gathering is not feasible

Proposed API:

class AuctionMaterialsBridge
{
public:
    /**
     * @brief Buy materials needed for recipe from auction house
     * @param bot Player bot
     * @param recipe Recipe that needs materials
     * @return true if all materials purchased
     */
    bool BuyMaterialsForRecipe(Player* bot, RecipeInfo const& recipe);

    /**
     * @brief Check if buying material is cheaper than gathering
     * @param bot Player bot
     * @param itemId Material item ID
     * @param quantity Amount needed
     * @return true if AH price < (time to gather × gold/hour rate)
     */
    bool IsBuyingCheaperThanGathering(Player* bot, uint32 itemId, uint32 quantity);

    /**
     * @brief Get best source for material (gather, craft, or buy)
     * @param bot Player bot
     * @param itemId Material item ID
     * @return MaterialSource enum (GATHER, CRAFT, BUY_AH, VENDOR)
     */
    MaterialSource GetBestMaterialSource(Player* bot, uint32 itemId);
};

---

3. System Integration Workflow

3.1 Automated Profession Leveling with Market Integration

User Goal: "Level Blacksmithing to 450 with profit"

System Flow:

1. ProfessionManager::AutoLevelProfession(player, BLACKSMITHING)
   ↓
2. GetOptimalLevelingRecipe(player, BLACKSMITHING)
   → Returns: "Thorium Bar" (skill 275-300, orange recipe)
   ↓
3. Check materials: GetMissingMaterials(recipe)
   → Needs: 200× Thorium Ore
   ↓
4. GatheringMaterialsBridge::GetBestMaterialSource(THORIUM_ORE)
   → Option A: Gather in Un'Goro Crater (30 min, free)
   → Option B: Buy from AH (5000g, instant)
   → Decision: GATHER (bot has time, no gold)
   ↓
5. GatheringManager::StartGatheringForMaterial(THORIUM_ORE, 200)
   → PathToNode(Un'Goro mining nodes)
   → GatherFromNode() × 50 nodes
   → Loot 200× Thorium Ore
   ↓
6. ProfessionManager::CraftItem(recipe, 100)  // 200 ore → 100 bars
   → Skill 275 → 295 (+20 skill points)
   ↓
7. AuctionManager::PostAuction(THORIUM_BAR, stackSize=20, buyout=market_price)
   → Post 5 stacks of 20 bars
   → Total value: 8000g
   ↓
8. AuctionEventBus::OnAuctionSold(itemId=THORIUM_BAR, profit=7500g)
   → Update statistics
   → Reinvest 5000g for next recipe

Profit: 7500g gold - 30 min gathering time = ~15,000 gold/hour Skill Gain: +20 skill points Efficiency: Fully automated gathering → crafting → selling pipeline

---

3.2 On-Demand Crafting with Material Acquisition

User Goal: "Craft 10× Titansteel Bar for raid consumables"

System Flow:

1. ProfessionManager::CraftItem(TITANSTEEL_BAR_RECIPE, 10)
   ↓
2. GetMissingMaterials(recipe)
   → Needs: 10× Titanium Bar, 10× Eternal Fire, 10× Eternal Earth, 10× Eternal Shadow
   ↓
3. For each material:
   a) Check inventory: GetItemCount()
   b) If missing, check best source:
      - GatheringMaterialsBridge::GetBestMaterialSource()
      - AuctionMaterialsBridge::IsBuyingCheaperThanGathering()
   ↓
4. Acquisition strategy:
   - Titanium Bar: BUY from AH (rare spawn, not worth farming)
   - Eternal Fire: GATHER in Wintergrasp (common, fast)
   - Eternal Earth: CRAFT from 10× Crystallized Earth (check AH for crystals)
   - Eternal Shadow: BUY from AH (dungeon drop, can't farm solo)
   ↓
5. Execute acquisition:
   a) AuctionManager::BuyoutAuction(TITANIUM_BAR) × 10
   b) GatheringManager::StartGatheringForMaterial(ETERNAL_FIRE, 10)
   c) AuctionManager::BuyoutAuction(CRYSTALLIZED_EARTH) × 100
   d) ProfessionManager::CraftItem(ETERNAL_EARTH_RECIPE, 10)
   e) AuctionManager::BuyoutAuction(ETERNAL_SHADOW) × 10
   ↓
6. All materials acquired → CraftItem(TITANSTEEL_BAR, 10)
   ↓
7. Store in bank or use for raid

Time: 15 min (10 min gathering + 5 min AH purchases) Cost: 2000g (AH purchases) Automation: 100% hands-free material acquisition

---

4. Implementation Roadmap

Phase 3A: Code Review & Cleanup (COMPLETED ✅)

• Fix ProfessionManager.cpp orphaned null checks (100+)
• Fix AuctionManager.cpp orphaned null checks (80+)
• Verify GatheringManager.cpp is production-ready
• Assess FarmingCoordinator integration state

Phase 3B: Bridge Implementation (NEXT)

1. Review ProfessionAuctionBridge (1-2 hours)

   • Verify current functionality
   • Add auto-sell feature for crafted items
   • Test with all 14 professions

2. Implement GatheringMaterialsBridge (4-6 hours)

   • Create new file: GatheringMaterialsBridge.h/cpp
   • Implement GetNeededMaterials()
   • Implement IsItemNeededForCrafting()
   • Implement PrioritizeNodesByNeeds()
   • Add to CMakeLists.txt
   • Full integration testing

3. Implement AuctionMaterialsBridge (4-6 hours)

   • Create new file: AuctionMaterialsBridge.h/cpp
   • Implement BuyMaterialsForRecipe()
   • Implement IsBuyingCheaperThanGathering() with time-value analysis
   • Implement GetBestMaterialSource() decision algorithm
   • Add to CMakeLists.txt
   • Full integration testing

4. Optional: Personal BankingManager (8-10 hours)

   • Extends BehaviorManager
   • Auto-deposit gold/items
   • Auto-withdraw materials
   • Integration with all other managers

Phase 3C: System Integration Testing (FINAL)

1. Test Scenario 1: Full profession leveling (Alchemy 1-450)
2. Test Scenario 2: Profit-driven crafting (flip Titansteel Bars)
3. Test Scenario 3: On-demand raid consumables
4. Test Scenario 4: Multi-bot coordinated farming + crafting
5. Performance testing: 1000 bots with all systems active
6. Memory profiling: Ensure no leaks in bridge classes

---

5. Architecture Recommendations

5.1 Should ProfessionManager Migrate to BehaviorManager?

Current: SINGLETON pattern Proposed: BehaviorManager pattern (like GatheringManager and AuctionManager)

Pros of Migration:

• ✅ Architectural consistency across all managers
• ✅ Throttled updates (reduce CPU usage)
• ✅ Built-in performance metrics
• ✅ OnInitialize/OnUpdate/OnShutdown lifecycle
• ✅ Thread-safe by design

Cons of Migration:

• ❌ Large refactoring effort (4-8 hours)
• ❌ Risk of breaking existing integrations (FarmingCoordinator, ProfessionAuctionBridge)
• ❌ Need to migrate per-bot instance data to member variables

Recommendation: DEFER to Phase 4

• Current SINGLETON pattern works fine for now
• All new bridges can wrap the singleton
• Migrate later when we have full test coverage

---

5.2 Event-Driven vs Polling Integration

Current Approach: Polling (managers check state every update)

Proposed Enhancement: Event-driven (managers subscribe to events)

Events to Add:

// ProfessionManager events
OnRecipeLearned(Player* bot, uint32 recipeId);
OnCraftingStarted(Player* bot, uint32 recipeId, uint32 quantity);
OnCraftingCompleted(Player* bot, uint32 itemId, uint32 quantity);
OnMaterialsNeeded(Player* bot, std::vector<std::pair<uint32, uint32>> materials);

// GatheringManager events
OnNodeDetected(Player* bot, GatheringNode const& node);
OnGatheringCompleted(Player* bot, uint32 itemId, uint32 quantity);
OnGatheringFailed(Player* bot, GatheringNode const& node);

// AuctionManager events (ALREADY EXISTS via AuctionEventBus)
OnAuctionPosted(Player* bot, uint32 auctionId, uint32 itemId);
OnAuctionSold(Player* bot, uint32 itemId, uint64 profit);
OnAuctionBought(Player* bot, uint32 itemId, uint64 cost);

Benefits:

• Reduces coupling between systems
• Enables reactive workflows (e.g., auto-sell when crafting completes)
• Better performance (no polling overhead)

Recommendation: Implement in Phase 3B

---

6. Deletion List

6.1 Advanced/EconomyManager.* (DUPLICATE - DELETE)

Reason: Broken duplicate of economy systems

Files to Delete:

• /home/user/TrinityCore/src/modules/Playerbot/Advanced/EconomyManager.h
• /home/user/TrinityCore/src/modules/Playerbot/Advanced/EconomyManager.cpp

Issues:

• 100+ syntax errors (stubs only)
• God class anti-pattern (auction + crafting + gathering + banking in one class)
• No thread safety
• Never implemented (only header declarations)

Keep Instead:

• Economy/AuctionManager.* (production-ready, BehaviorManager pattern)
• Professions/ProfessionManager.* (production-ready, SINGLETON pattern)
• Professions/GatheringManager.* (production-ready, BehaviorManager pattern)

---

7. Testing Checklist

Unit Tests

• ProfessionManager::GetMissingMaterials() accuracy
• GatheringMaterialsBridge::PrioritizeNodesByNeeds() sorting
• AuctionMaterialsBridge::IsBuyingCheaperThanGathering() calculation
• BankingManager::AutoDepositJunk() item filtering

Integration Tests

• Full profession leveling flow (1-450 all professions)
• Material acquisition decision tree (gather vs buy vs craft)
• Auction posting after crafting automation
• Cross-manager event propagation

Performance Tests

• 1000 bots with all managers active (CPU < 50%)
• Bridge method latency (all < 1ms)
• Memory usage with 5000 bots (no leaks)

Edge Case Tests

• No materials available (gathering or AH)
• Insufficient gold to buy materials
• Profession not learned but recipe queued
• Bank full when auto-deposit triggered

---

8. Summary

Current State:

• 3 production-ready managers (Profession, Gathering, Auction)
• 1 missing manager (personal Banking)
• 1 existing bridge (ProfessionAuctionBridge - needs review)
• 2 needed bridges (GatheringMaterials, AuctionMaterials)

Next Steps:

1. ✅ Fix compilation blockers (DONE - 180+ orphaned null checks removed)
2. ▶️ Review ProfessionAuctionBridge (NEXT)
3. ⏳ Implement GatheringMaterialsBridge
4. ⏳ Implement AuctionMaterialsBridge
5. ⏳ Delete Advanced/EconomyManager duplicate
6. ⏳ Optional: Implement personal BankingManager
7. ⏳ Full integration testing

Estimated Completion: 12-20 hours of development + testing

---

Document Version: 1.0 Last Updated: 2025-11-10 Next Review: After Phase 3B completion