# Graph Package

The `graph` package provides advanced graph database operations for industrial symbiosis analysis using Neo4j. It follows clean architecture principles with clear separation of concerns.

## Architecture

The package is organized into focused components:

- **types.go**: Domain types and data structures
- **config.go**: Configuration management
- **errors.go**: Custom error definitions
- **session_manager.go**: Neo4j session lifecycle management
- **query_templates.go**: Reusable Cypher query templates
- **node_converter.go**: Neo4j node/relationship conversion utilities
- **traversal.go**: Graph traversal operations (chains, networks)
- **path_finder.go**: Path finding algorithms (optimal paths)
- **network_analyzer.go**: Network analysis (centrality, statistics, cycles)
- **calculator.go**: Main facade/interface
- **factory.go**: Factory functions for easy instantiation

## Usage

### Basic Usage

```go
import "bugulma/backend/internal/graph"

// Create calculator with defaults
calc := graph.NewCalculatorWithDefaults(neo4jDriver, "database_name")

// Find resource chains
chains, err := calc.FindResourceChains(ctx, domain.ResourceType("biowaste"), 5, 1000.0)

// Find symbiosis networks
networks, err := calc.FindSymbiosisNetworks(ctx, 3, 20)

// Find optimal paths
paths, err := calc.FindOptimalResourcePaths(ctx, "org1", "org2", domain.ResourceType("heat"), 4)

// Analyze network centrality
centrality, err := calc.AnalyzeNetworkCentrality(ctx)

// Get network statistics
stats, err := calc.GetNetworkStatistics(ctx)

// Find circular economy cycles
cycles, err := calc.FindCircularEconomyCycles(ctx)
```

### Custom Configuration

```go
config := &graph.Config{
    MaxChainLength:     10,
    MaxPathHops:        6,
    MaxNetworkSize:     30,
    MinNetworkSize:     2,
    DefaultResultLimit: 100,
    MaxChainDistanceKm: 1000.0,
    QueryTimeoutSeconds: 60,
}

calc := graph.NewCalculator(neo4jDriver, "database_name", config)
```

## Components

### SessionManager

Manages Neo4j sessions with proper lifecycle management, timeouts, and error handling.

### QueryTemplates

Contains reusable Cypher query templates following Neo4j best practices. All queries are parameterized for security and performance.

### Traversal

Handles graph traversal operations:
- Finding resource chains through multiple parties
- Identifying symbiosis networks
- Detecting circular resource flows

### PathFinder

Implements path finding algorithms:
- Shortest path by cost
- Optimal resource flow paths
- Multi-hop connections

### NetworkAnalyzer

Provides network analysis capabilities:
- Centrality metrics (degree, betweenness, closeness)
- Network statistics
- Circular economy cycle detection

## Query Patterns

All queries follow Neo4j best practices:

1. **Parameterized queries**: All user input is parameterized
2. **Index usage**: Queries leverage Neo4j indexes
3. **Path constraints**: Variable-length paths with reasonable limits
4. **Spatial calculations**: Uses Neo4j's spatial functions for distance
5. **Aggregation**: Efficient use of Cypher aggregation functions

## Error Handling

The package defines custom errors for common scenarios:
- `ErrInvalidConfig`: Invalid configuration
- `ErrInvalidQuery`: Invalid query
- `ErrNoResults`: No results found
- `ErrQueryTimeout`: Query timeout
- `ErrGDSNotAvailable`: Graph Data Science library not available

## Performance Considerations

- **Query timeouts**: Configurable query timeouts prevent hanging queries
- **Result limits**: Default limits prevent excessive result sets
- **Distance constraints**: Maximum distance limits reduce search space
- **Index usage**: Queries are designed to leverage Neo4j indexes

## Testing

The package is designed for testability:
- All components accept interfaces where possible
- Session management is abstracted
- Query templates can be mocked
- Node conversion is isolated

## Future Enhancements

- GDS (Graph Data Science) library integration for advanced algorithms
- Caching layer for frequently accessed data
- Batch operations for bulk analysis
- Streaming results for large datasets