turash/bugulma/backend/internal/graph

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

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

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