turash/concept/07_entity_relationships.md

5. Entity Relationships

The platform uses a three-tier entity model to accurately represent real-world industrial ecosystems:

Business Entity

Represents the legal/commercial entity - the company that SMEs identify with. Contains business capabilities, certifications, strategic profile, and relationships.

Site Entity

Represents physical locations/buildings where business activities occur. A business can operate at multiple sites (multi-site operations, industrial parks). Sites have their own infrastructure, utilities, and environmental characteristics.

Resource Flows

Attached to specific sites where they physically occur, owned by businesses. This allows:

• Multi-site businesses with different resource profiles per location
• Shared assets located at specific sites
• Accurate geographical matching and logistics planning

Relationship: Business owns/operates Sites, Sites host ResourceFlows and SharedAssets.

Multi-Modal Matching

The same engine now matches across 4 dimensions:

1. Resource flows (original): Physics-based surplus-to-demand
2. Service complementarity: "I service compressors, you have 30 compressors"
3. Product supply chains: "I need packaging, you produce it 2km away"
4. Compliance networks: "We both need oil separator cleaning → group buy"

UX Features for Felt Value

"Nearby Buyers & Suppliers"

Every resource card shows:

• Resource matches (existing functionality)
• Relevant suppliers (products for this process)
• Service providers (equipment maintenance)

"Shared OPEX Deals"

Cluster by recurring costs and offer group discounts:

• "3 of you can save 12% on waste pickup"
• "5 companies can get PPE bulk pricing"

"Opportunities Feed"

Timeline of local business opportunities:

• "Bakery A needs cold storage 5-10 m³ nearby"
• "Packaging C wants new suppliers within 10 km"
• "Pool B can take 20 kW low-temp heat"

Service-as-a-Resource

Formalize services as first-class resources:

For complete ResourceFlow schema, see schemas/resource_flow.json

Now match: "Plant emits 'faulty pumps' → 3 local companies output 'pump maintenance within 25km'"

Layered Architecture

Layer 1 (Core): Strict, typed, physics/economics-checked flows
Layer 2 (Business): Fuzzy, texty, lower-trust, human-verified

Matching priority:

1. Try hard match (physics)
2. If <N results, add soft match (business/services)
3. Surface both but label differently

This keeps the platform serious for utilities while being sticky for SMEs.

Match State Management & Conflict Resolution

Edge State Machine (prevents double-booking of matches):

• suggested: Match discovered by algorithm
• negotiating: Both parties contacted, initial discussions
• reserved: Match committed to (exclusive for N days)
• contracted: Legal agreement signed
• live: Implementation in progress
• failed: Match abandoned

Conflict Resolution: When multiple buyers want same resource:

• Priority: Contracted > Reserved > Negotiating > Suggested
• Time-based: First to reserve gets priority
• Economic: Higher value matches override lower ones

Execution Support Entities

Match Packet (partner-ready deliverables):

For complete MatchPacket schema, see schemas/match_packet.json

Facilitator Marketplace (external engineers as paid intermediaries):

For complete Facilitator schema, see schemas/facilitator.json

---