turash/docs/concept/09_graph_database_design.md

7. Graph Database Design

Base Technology

Graph Database Selection: Start with Neo4j for MVP (best documentation, largest ecosystem), plan migration path to TigerGraph if scale exceeds 10B nodes.

Decision Criteria:

1. Scalability:

   • Neo4j: Strong until ~50B nodes, then requires clustering
   • ArangoDB: Better horizontal scaling
   • TigerGraph: Designed for very large graphs (100B+ nodes)
   • Memgraph: Fast but less mature ecosystem

2. Geospatial Support:

   • Neo4j: Requires APOC library + PostGIS integration
   • ArangoDB: Built-in geospatial indexes
   • TigerGraph: Requires external PostGIS

3. Query Performance: Benchmark common queries (5km radius, temporal overlap, quality matching)

4. Ecosystem: Community size, cloud managed options, integration with existing stack

5. Cost: Licensing, cloud costs, operational complexity

Relationships

(Business)-[:OPERATES_AT]->(Site)
(Site)-[:HOSTS]->(ResourceFlow)
(ResourceFlow)-[:MATCHABLE_TO {efficiency, distance, savings}]->(ResourceFlow)
(Site)-[:HOSTS]->(SharedAsset)
(Business)-[:OFFERS]->(Service)
(Business)-[:SELLS]->(Product)

Hybrid Architecture for Geospatial Queries

Architecture:

• Neo4j: Stores graph structure, relationships, quality/temporal properties
• PostgreSQL+PostGIS: Stores detailed geospatial data, handles complex distance calculations, spatial joins
• Synchronization: Event-driven sync (Site created/updated → sync to PostGIS)

Query Pattern:

1. PostGIS: Find all sites within 5km radius (fast spatial index)
2. Neo4j: Filter by ResourceFlow types, quality, temporal overlap (graph traversal)
3. Join results in application layer or use Neo4j spatial plugin

Alternative: Use Neo4j APOC spatial procedures if graph is primary store.

Zone-First Architecture for Data Sovereignty

Problem: Global graph vs local adoption conflict - EU-wide matching requires unified schema, but local clusters need low-latency, sovereign data control.

Solution: Zone-first graph architecture where each geographic/regulatory zone operates semi-autonomously:

Zone Types:

• City Zones: Municipal boundaries, operated by city governments
• Industrial Park Zones: Single park operators, private industrial clusters
• Regional Zones: County/state level, cross-municipality coordination
• Country Zones: National regulatory compliance, standardized schemas

Architecture Pattern:

Zone Database (Local Neo4j/PostgreSQL)
├── Local Graph: Sites, flows, businesses within zone
├── Local Rules: Zone-specific matching logic, regulations
├── Selective Publishing: Choose what to expose globally
└── Data Sovereignty: Zone operator controls data visibility

Global Federation Layer
├── Cross-zone matching requests
├── Federated queries (zone A requests zone B data)
├── Anonymized global analytics
└── Selective data sharing agreements

Key Benefits:

• Data Sovereignty: Cities/utilities control their data, GDPR compliance
• Low Latency: Local queries stay within zone boundaries
• Regulatory Flexibility: Each zone adapts to local waste/energy rules
• Scalable Adoption: Start with single zones, federate gradually
• Trust Building: Local operators maintain control while enabling cross-zone matches

Implementation:

• Zone Registry: Global catalog of active zones with API endpoints
• Federation Protocol: Standardized cross-zone query interface
• Data Contracts: Per-zone agreements on what data is shared globally
• Migration Path: Start mono-zone, add federation as network grows

Indexing Strategy

Required Indexes:

• Spatial Index: Site locations (latitude, longitude)
• Temporal Index: ResourceFlow availability windows, seasonality
• Composite Indexes:
  • (ResourceFlow.type, ResourceFlow.direction, Site.location)
  • (ResourceFlow.quality.temperature_celsius, ResourceFlow.type)
• Full-Text Search: Business names, NACE codes, service domains

Index Maintenance:

• Monitor query performance and index usage
• Use Neo4j's EXPLAIN PROFILE for query optimization
• Consider partitioning large graphs by geographic regions

Why Graph DB

Queries like: "find all output nodes within 5 km producing heat 35–60 °C that matches any input nodes needing heat 30–55 °C, ΔT ≤ 10 K, availability overlap ≥ 70 %, and net savings > €0.02/kWh."

That's a multi-criteria graph traversal — perfect fit.

---