#pragma once

#include <string>
#include <nlohmann/json.hpp>

// Forward declarations
namespace warfactory {
    class IIO;
    class ITaskScheduler;
}

using json = nlohmann::json;

namespace warfactory {

/**
 * @brief Task scheduling interface for module delegation
 *
 * Allows modules to delegate tasks to their execution system without
 * knowing the underlying implementation (sequential, threaded, thread pool).
 */
class ITaskScheduler {
public:
    virtual ~ITaskScheduler() = default;

    /**
     * @brief Schedule a task for execution
     * @param taskType Type of task (e.g., "pathfinding", "collision_check")
     * @param taskData JSON data for the task
     */
    virtual void scheduleTask(const std::string& taskType, const json& taskData) = 0;

    /**
     * @brief Check if completed tasks are available
     * @return Number of completed tasks ready to be pulled
     */
    virtual int hasCompletedTasks() const = 0;

    /**
     * @brief Pull and consume one completed task
     * @return Task result JSON. Task is removed from completed queue.
     */
    virtual json getCompletedTask() = 0;
};


/**
 * @brief Pure business logic interface - optimized for Claude Code development
 *
 * This interface defines the contract for all game modules. Each module contains
 * 200-300 lines of pure game logic with zero infrastructure code.
 *
 * Key design principles:
 * - PURE FUNCTION: process() method has no side effects beyond return value
 * - JSON ONLY: All communication via JSON input/output
 * - NO INFRASTRUCTURE: No threading, networking, or framework dependencies
 * - HOT-RELOAD READY: State serialization for seamless module replacement
 * - CLAUDE OPTIMIZED: Micro-context size for AI development efficiency
 *
 * Module constraint: Maximum 300 lines per module (Exception: ProductionModule 500-800 lines)
 */
class IModule {
public:
    virtual ~IModule() = default;

    /**
     * @brief Process game logic
     * @param input JSON input from other modules or the module system
     *
     * This is the core method where all module logic is implemented.
     * Modules communicate via IIO pub/sub and can delegate tasks via ITaskScheduler.
     * Must handle state properly through getState/setState for hot-reload.
     */
    virtual void process(const json& input) = 0;

    /**
     * @brief Initialize module with configuration and services
     * @param config JSON configuration specific to this module
     * @param io Pub/sub communication interface for messaging
     * @param scheduler Task scheduling interface for delegating work
     *
     * Called once when the module is first loaded. Should setup any
     * internal state, validate configuration, and store service references.
     */
    virtual void initialize(const json& config, IIO* io, ITaskScheduler* scheduler) = 0;

    /**
     * @brief Cleanup and shutdown the module
     *
     * Called when the module is being unloaded. Should clean up any
     * resources and prepare for safe destruction.
     */
    virtual void shutdown() = 0;

    /**
     * @brief Get current module state for hot-reload support
     * @return JSON representation of all module state
     *
     * Critical for hot-reload functionality. Must serialize all internal
     * state that needs to be preserved when the module is replaced.
     * The returned JSON should be sufficient to restore the module to
     * its current state via setState().
     */
    virtual json getState() = 0;

    /**
     * @brief Restore module state after hot-reload
     * @param state JSON state previously returned by getState()
     *
     * Called after module replacement to restore the previous state.
     * Must be able to reconstruct all internal state from the JSON
     * to ensure seamless hot-reload without game disruption.
     */
    virtual void setState(const json& state) = 0;

    /**
     * @brief Get module type identifier
     * @return Module type as string (e.g., "tank", "economy", "production")
     */
    virtual std::string getType() const = 0;
};

} // namespace warfactory