aissia/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

// 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:

{
  "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

// 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

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

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// 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.