mirror of
https://github.com/SamyRai/turash.git
synced 2025-12-26 23:01:33 +00:00
000eab4740
Repository Structure:
- Move files from cluttered root directory into organized structure
- Create archive/ for archived data and scraper results
- Create bugulma/ for the complete application (frontend + backend)
- Create data/ for sample datasets and reference materials
- Create docs/ for comprehensive documentation structure
- Create scripts/ for utility scripts and API tools
Backend Implementation:
- Implement 3 missing backend endpoints identified in gap analysis:
* GET /api/v1/organizations/{id}/matching/direct - Direct symbiosis matches
* GET /api/v1/users/me/organizations - User organizations
* POST /api/v1/proposals/{id}/status - Update proposal status
- Add complete proposal domain model, repository, and service layers
- Create database migration for proposals table
- Fix CLI server command registration issue
API Documentation:
- Add comprehensive proposals.md API documentation
- Update README.md with Users and Proposals API sections
- Document all request/response formats, error codes, and business rules
Code Quality:
- Follow existing Go backend architecture patterns
- Add proper error handling and validation
- Match frontend expected response schemas
- Maintain clean separation of concerns (handler -> service -> repository)
138 lines
4.0 KiB
Markdown
138 lines
4.0 KiB
Markdown
# 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
|
|
|