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:

```go
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**:
```go
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**:
```go
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

```go
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

```go
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:

```bash
# 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