turash/bugulma/backend/internal/matching/plugins/README.md

Matching Plugins

The plugins package provides a modular plugin architecture for resource-specific matching logic in the industrial symbiosis platform. This allows for specialized algorithms and validation rules for different resource types.

Architecture

The plugin system follows the same clean architecture principles as the rest of the codebase:

• Plugin Interface: Defines the contract that all plugins must implement
• Plugin Registry: Manages plugin registration and discovery
• Plugin Manager: Integrates plugins with the matching engine
• Concrete Plugins: Resource-specific implementations

Plugin Interface

All plugins must implement the Plugin interface:

type Plugin interface {
    Name() string
    ResourceType() domain.ResourceType
    SupportsQualityCheck() bool
    SupportsEconomicCalculation() bool
    SupportsTemporalCheck() bool
    CheckQualityCompatibility(source, target *domain.ResourceFlow) (float64, error)
    CalculateEconomicImpact(source, target *domain.ResourceFlow, distance float64) (float64, error)
    CheckTemporalCompatibility(source, target *domain.ResourceFlow) (float64, error)
    ValidateCandidate(candidate *engine.Candidate) (bool, string)
}

Built-in Plugins

Heat Plugin

Resource Type: heat

Features:

• Temperature compatibility validation (±15°C tolerance)
• Pressure matching considerations
• Heat loss calculation over distance
• Steam vs. hot water conversion penalties
• Seasonal demand analysis
• Transport cost modeling

Configuration:

config := &HeatPluginConfig{
    MaxTempDiffCelsius:     15.0,
    TempTolerancePenalty:   0.2,
    PressureToleranceBar:   2.0,
    PressureMatchBonus:     0.1,
    HeatLossPerKm:          0.02,
    MinEfficiencyThreshold: 0.7,
    HeatValuePerDegC:       50.0,
    TransportCostPerKm:     1000.0,
    PumpCostPerBar:         500.0,
    MinOverlapHours:        100.0,
    SeasonalBonus:          0.15,
}

Biowaste Plugin

Resource Type: biowaste

Features:

• Contamination level validation (max 5%)
• Moisture content requirements (40-80%)
• Biodegradability assessment
• Certification compatibility checks
• Short shelf-life considerations
• Waste disposal savings calculation
• Distance constraints for perishability

Configuration:

config := &BiowastePluginConfig{
    MaxContaminantPct:      5.0,
    ContaminationPenalty:   0.3,
    MinMoisturePct:         40.0,
    MaxMoisturePct:         80.0,
    MoistureMismatchPenalty: 0.15,
    MinBiodegradabilityPct: 70.0,
    BiodegradabilityBonus:  0.1,
    RequiredCertifications: []string{"ISO 14001", "HACCP"},
    CertificationBonus:     0.1,
    WasteDisposalSavings:   50.0,
    TransportCostPerKm:     0.5,
    ProcessingCostPerTonne: 20.0,
    MaxTransportDistance:   100.0,
    DistancePenaltyFactor:  0.01,
    ShelfLifeDays:          7,
    StorageCostPerDay:      2.0,
}

Usage

Basic Usage

import "bugulma/backend/internal/matching/plugins"

// Create registry and register plugins
registry := plugins.NewRegistry()
plugins.RegisterDefaultPlugins(registry)

// Create plugin manager
pluginManager := plugins.NewManager(registry, matchingEngine)

// Use in matching service
service := matching.NewService(/* dependencies */, eventBus)

Custom Plugin

type CustomPlugin struct {
    config *CustomConfig
}

func (cp *CustomPlugin) Name() string {
    return "custom_plugin"
}

func (cp *CustomPlugin) ResourceType() domain.ResourceType {
    return domain.TypeWater
}

func (cp *CustomPlugin) CheckQualityCompatibility(source, target *domain.ResourceFlow) (float64, error) {
    // Custom quality logic for water
    var sourceQuality, targetQuality domain.Quality
    json.Unmarshal(source.Quality, &sourceQuality)
    json.Unmarshal(target.Quality, &targetQuality)

    // Water-specific quality checks
    score := 1.0

    // pH compatibility
    if sourceQuality.PhLevel != nil && targetQuality.PhLevel != nil {
        phDiff := math.Abs(*sourceQuality.PhLevel - *targetQuality.PhLevel)
        if phDiff > 2.0 {
            score -= 0.3 // Significant penalty for pH mismatch
        }
    }

    return score, nil
}

// Register custom plugin
registry.Register(&CustomPlugin{config: defaultConfig})

Integration with Matching Engine

The plugin system integrates seamlessly with the existing matching engine:

1. Pre-matching: Basic compatibility checks using standard engine
2. Enhancement: Plugin-specific logic enhances candidate evaluation
3. Validation: Plugin validation ensures resource-specific requirements
4. Ranking: Enhanced scores are used for final candidate ranking

Plugin Development Guidelines

1. Resource-Specific Logic

• Focus on domain-specific requirements and constraints
• Implement realistic economic calculations
• Consider regulatory and safety requirements

2. Error Handling

• Return descriptive errors for validation failures
• Use appropriate error types for different failure modes
• Log warnings for non-critical issues

3. Performance

• Keep calculations efficient for real-time matching
• Cache expensive operations when possible
• Use appropriate data structures for lookups

4. Configuration

• Make all thresholds and penalties configurable
• Provide sensible defaults
• Validate configuration on initialization

5. Testing

• Test all plugin methods with various scenarios
• Include edge cases and error conditions
• Test integration with the matching engine

Testing

The plugin system includes comprehensive tests:

# Run plugin tests
go test ./internal/matching/plugins/...

# Run integration tests
go test ./internal/matching/...

Future Enhancements

• Plugin Marketplace: Allow third-party plugins
• Hot Reloading: Update plugins without restarting
• Plugin Metrics: Monitor plugin performance and usage
• Configuration UI: Web interface for plugin configuration
• Plugin Dependencies: Support for plugin interdependencies

Benefits

1. Modularity: Resource-specific logic is isolated and maintainable
2. Extensibility: Easy to add support for new resource types
3. Quality: Specialized algorithms improve matching accuracy
4. Performance: Plugins can optimize for specific use cases
5. Safety: Domain constraints prevent invalid matches