warfactoryracine/docs/04-reference/INTEGRATION-MASTER-LIST.md

# INTEGRATION MASTER LIST

Complete technical specifications catalog for the Warfactory project.

## Global Architecture Overview

### System Orchestration Flow
```
MainServer Process:
├── CoordinationModule (Global Orchestrator)
│   ├── Loads gameconfig.json via IDataTree
│   ├── Launches local IEngine + modules
│   └── Launches remote servers + engines
├── Local IEngine (manages local modules)
│   ├── IModuleSystem (execution strategy)
│   └── Local Modules (.so files)
└── Remote Servers (launched by coordination)
    ├── Remote IEngine (manages remote modules)
    ├── IModuleSystem (execution strategy)
    └── Remote Modules (.so files)
```

### Startup Sequence
1. **MainServer** starts and launches **CoordinationModule**
2. **CoordinationModule** calls `startNewGame("gameconfig.json")`
3. **Config Loading**: IDataTree loads and parses gameconfig.json
4. **Deployment Analysis**: Parse deployment section to determine module topology
5. **Local Deployment**: Deploy modules with `target: "local"` to local IEngine
6. **Remote Deployment**: Launch remote servers and deploy modules with `target: "server:IP"`
7. **Synchronization**: All modules receive their configuration via `setConfiguration()`
8. **Game Ready**: Return control to user interface

### Module Lifecycle with New Configuration System
```cpp
// Old way (DEPRECATED)
module->initialize(json_config, io, scheduler);

// New way (CURRENT)
const IDataNode& config = configTree->getNode("modules/production");
module->setConfiguration(config, io, scheduler);  // const ref, no copies

// Health monitoring
json health = module->getHealthStatus();
// Returns: {"status": "healthy", "last_process_time_ms": 1.2, "memory_usage_mb": 45}
```

## Core Interface System

### Engine Interfaces (IMMUTABLE)
- **IEngine**: Engine orchestration, module loading, client/coordinator socket management
- **IModuleSystem**: Execution strategy + task scheduling (inherits ITaskScheduler)
- **IModule**: Pure business logic + pub/sub communication + task delegation (**BREAKING CHANGES**)
- **IIO**: Pull-based pub/sub with low-frequency batching and health monitoring
- **ITaskScheduler**: Task delegation interface for module → execution system

### Configuration System (IMMUTABLE)
- **IDataTree**: Configuration tree container with manual hot-reload capabilities
- **IDataNode**: Hierarchical data nodes with pattern matching and property queries (**const methods**)
- **DataTreeFactory**: Factory pattern for flexible data source creation

### Coordination System (NEW)
- **ICoordinationModule**: Global system orchestrator and main game lifecycle manager

## GameConfig.json Architecture

### Central Configuration System
The entire game system is configured through a single **`gameconfig.json`** file that serves as the master configuration:

```json
{
  "game": {
    "name": "Warfactory Game Session",
    "version": "1.0.0",
    "save_path": "./saves/game_001"
  },
  "deployment": {
    "modules": [
      {
        "id": "production_main",
        "type": "ProductionModule",
        "path": "./modules/production.so",
        "target": "local",
        "config_path": "modules/production"
      },
      {
        "id": "economy_central",
        "type": "EconomyModule",
        "path": "./modules/economy.so",
        "target": "server:192.168.1.100:8080",
        "config_path": "modules/economy"
      },
      {
        "id": "tank_combat",
        "type": "TankModule",
        "path": "./modules/tank.so",
        "target": "cluster:combat_nodes",
        "config_path": "modules/tank"
      }
    ]
  },
  "modules": {
    "production": {
      "frequency": "60Hz",
      "belt_speed": 2.5,
      "inserter_capacity": 12
    },
    "economy": {
      "frequency": "0.1Hz",
      "inflation_rate": 0.02,
      "market_volatility": 0.15
    },
    "tank": {
      "targeting_frequency": "60Hz",
      "movement_frequency": "30Hz",
      "tactical_frequency": "1Hz"
    }
  }
}
```

### Configuration Flow
1. **CoordinationModule** loads `gameconfig.json` via IDataTree
2. **Deployment section** defines module topology and distribution
3. **Modules section** contains hierarchical configuration for each module type
4. **Hot-reload** updates propagated to all deployed modules automatically

### CoordinationModule Deployment Logic
```cpp
// Example deployment process
void CoordinationModule::deployModule(const std::string& moduleInstanceId) {
    // 1. Get module configuration from gameconfig.json
    const IDataNode& deployConfig = configTree->getNode("deployment/modules");
    const IDataNode* moduleConfig = deployConfig.getFirstChildByName(moduleInstanceId);

    // 2. Determine deployment target
    std::string target = moduleConfig->getString("target");
    std::string modulePath = moduleConfig->getString("path");
    std::string configPath = moduleConfig->getString("config_path");

    // 3. Get module-specific configuration
    const IDataNode& moduleSettings = configTree->getNode("modules/" + configPath);

    // 4. Deploy based on target
    if (target == "local") {
        localEngine->getModuleSystem()->loadModule(modulePath, moduleSettings);
    } else if (target.startswith("server:")) {
        deployToRemoteServer(target, modulePath, moduleSettings);
    }
}
```

## IDataTree Configuration System Specifications

### Core Architecture
```cpp
namespace warfactory {
    class IDataTree {
        // Tree access
        virtual std::unique_ptr<IDataNode> getRoot() = 0;
        virtual std::unique_ptr<IDataNode> getNode(const std::string& path) = 0;

        // Manual hot-reload
        virtual bool checkForChanges() = 0;
        virtual bool reloadIfChanged() = 0;
        virtual void onTreeReloaded(std::function<void()> callback) = 0;

        // Metadata
        virtual std::string getType() = 0;
    };
}
```

### IDataNode Capabilities
```cpp
namespace warfactory {
    class IDataNode {
        // Tree navigation
        virtual std::unique_ptr<IDataNode> getChild(const std::string& name) = 0;
        virtual std::vector<std::string> getChildNames() = 0;
        virtual bool hasChildren() = 0;

        // Exact search in children
        virtual std::vector<IDataNode*> getChildrenByName(const std::string& name) = 0;
        virtual bool hasChildrenByName(const std::string& name) const = 0;
        virtual IDataNode* getFirstChildByName(const std::string& name) = 0;

        // Pattern matching search (deep search in whole subtree)
        virtual std::vector<IDataNode*> getChildrenByNameMatch(const std::string& pattern) = 0;
        virtual bool hasChildrenByNameMatch(const std::string& pattern) const = 0;
        virtual IDataNode* getFirstChildByNameMatch(const std::string& pattern) = 0;

        // Query by properties
        virtual std::vector<IDataNode*> queryByProperty(const std::string& propName,
                                                       const std::function<bool(const json&)>& predicate) = 0;

        // Node's own data
        virtual json getData() = 0;
        virtual bool hasData() = 0;
        virtual void setData(const json& data) = 0;

        // Typed data access by property name
        virtual std::string getString(const std::string& name, const std::string& defaultValue = "") = 0;
        virtual int getInt(const std::string& name, int defaultValue = 0) = 0;
        virtual double getDouble(const std::string& name, double defaultValue = 0.0) = 0;
        virtual bool getBool(const std::string& name, bool defaultValue = false) = 0;
        virtual bool hasProperty(const std::string& name) = 0;

        // Hash system for validation & synchro
        virtual std::string getDataHash() = 0;
        virtual std::string getTreeHash() = 0;
        virtual std::string getSubtreeHash(const std::string& childPath) = 0;

        // Metadata
        virtual std::string getPath() = 0;
        virtual std::string getName() = 0;
        virtual std::string getNodeType() = 0;
    };
}
```

### Configuration Usage Patterns

#### Hierarchical Data Access
```cpp
// Access nested configuration
std::unique_ptr<IDataTree> tree = DataTreeFactory::create("json", "config/vehicles.json");
std::unique_ptr<IDataNode> tank = tree->getNode("vehicles/tanks/heavy/model5");

// Get properties with type safety
int armor = tank->getInt("armor", 100);
double speed = tank->getDouble("speed", 30.0);
std::string name = tank->getString("display_name", "Unknown Tank");
```

#### Pattern Matching Search
```cpp
// Find all components
std::vector<IDataNode*> components = root->getChildrenByNameMatch("component*");

// Find all heavy variants
std::vector<IDataNode*> heavyUnits = root->getChildrenByNameMatch("*heavy*");

// Find specific models
std::vector<IDataNode*> models = root->getChildrenByNameMatch("model_*");
```

#### Property-Based Queries
```cpp
// Find all tanks with armor > 150
std::vector<IDataNode*> heavyTanks = root->queryByProperty("armor", [](const json& val) {
    return val.is_number() && val.get<int>() > 150;
});

// Find all vehicles with specific role
std::vector<IDataNode*> scouts = root->queryByProperty("role", [](const json& val) {
    return val.is_string() && val.get<std::string>() == "scout";
});
```

#### Hot-Reload Workflow
```cpp
// Manual hot-reload check
if (tree->checkForChanges()) {
    if (tree->reloadIfChanged()) {
        // Tree was reloaded - update dependent systems
        updateGameContent();
    }
}

// Register reload callback
tree->onTreeReloaded([]() {
    std::cout << "Configuration reloaded - updating systems\n";
    notifyAllModules();
});
```

### Hash-Based Validation
```cpp
// Validate specific data integrity
std::string nodeHash = node->getDataHash();
std::string previousHash = loadStoredHash();
if (nodeHash != previousHash) {
    // Data has changed - trigger update
    synchronizeWithServer(nodeHash);
}

// Validate entire subtree
std::string treeHash = node->getTreeHash();
if (treeHash != expectedTreeHash) {
    // Subtree structure or data has changed
    performFullValidation();
}
```

### Factory Pattern Usage
```cpp
// JSON configuration
std::unique_ptr<IDataTree> jsonTree = DataTreeFactory::create("json", "config/vehicles.json");

// Future: Database configuration
std::unique_ptr<IDataTree> dbTree = DataTreeFactory::create("database", "postgresql://config_db");

// Future: Network configuration
std::unique_ptr<IDataTree> netTree = DataTreeFactory::create("network", "https://api.example.com/config");
```

## UI Interface System (COMPLETED)

### IUI Architecture
- **Data-Agnostic Design**: Generic interface supporting all content types
- **Type-Safe Enums**: DataType::ECONOMY, RequestType::GET_PRICES for performance
- **Hierarchical Windowing**: Parent → Dock → Split → Tab → Window structure
- **Hybrid Sizing System**: Percentage targets with absolute pixel constraints

### ImGuiUI Implementation
- **Complete Rendering Pipeline**: All DataType content renderers implemented
- **Interactive Callbacks**: Request/response system with onRequest() + custom events
- **Professional Layout**: Economic topbar + companies panel + strategic map + console
- **State Management**: Window persistence, docking configuration, layout serialization

## Module System Specifications

### BREAKING CHANGES in IModule Interface
```cpp
// OLD Interface (DEPRECATED)
class IModule {
    virtual void initialize(const json& config, IIO* io, ITaskScheduler* scheduler) = 0;
    virtual bool isHealthy() = 0;  // Simple boolean
};

// NEW Interface (CURRENT)
class IModule {
    virtual void setConfiguration(const IDataNode& configNode, IIO* io, ITaskScheduler* scheduler) = 0;
    virtual const IDataNode& getConfiguration() = 0;
    virtual json getHealthStatus() = 0;  // Detailed JSON report
    // initialize() method REMOVED
};
```

### Configuration Immutability Pattern
```cpp
// Modules receive const references - cannot modify configuration
const IDataNode& config = coordinationModule->getConfigurationTree()->getNode("modules/production");

// All getter methods are const to enforce read-only access
int frequency = config.getInt("frequency", 60);  // const method
std::string mode = config.getString("mode", "auto");  // const method

// Modifications only possible through CoordinationModule
coordinationModule->syncConfiguration();  // Reloads entire tree
```

### Module Health Monitoring
```cpp
// Detailed health status example
json healthStatus = {
    "status": "healthy|degraded|critical|offline",
    "last_process_time_ms": 1.2,
    "memory_usage_mb": 45,
    "error_count": 0,
    "warnings": ["High memory usage detected"],
    "details": "All subsystems operational",
    "uptime_seconds": 3600,
    "processed_messages": 15420
};
```

### Module Frequencies & Isolation
- **ProductionModule**: 60Hz (frame-perfect factory operations)
- **TankModule**: 0.1-60Hz (Targeting 60Hz → Movement 30Hz → Tactical 1Hz → Analytics 0.1Hz)
- **EconomyModule**: 0.01-0.1Hz (economic cycles)
- **War Isolation**: ZERO interaction ProductionModule ↔ WarModule
- **Supply Chain**: Factory → LogisticModule → War (unidirectional flow)

### Performance Targets
- **V1 Client**: 30+ fps
- **V2 Client**: 60+ fps
- **V1 Server**: 10+ players
- **V2 Server**: 100+ players

## Development Constraints

### Code Restrictions
- **AUTO KEYWORD PROHIBITED**: Explicit types required throughout codebase
- **Interface Immutability**: Core interfaces NEVER modified once finalized
- **Module Isolation**: No `#include "../"` or parent directory references
- **PUB/SUB Communication**: Module communication via IIO only

### Build System
- **Autonomous Builds**: Each module builds independently
- **Hot-Reload**: 0.4ms average reload time achieved
- **Cross-Platform**: Linux development → Windows .exe automated
- **Debug Tools**: AddressSanitizer + UndefinedBehaviorSanitizer by default

This document serves as the authoritative reference for all technical specifications in the Warfactory project.