## 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](./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](./schemas/match_packet.json)*

**Facilitator Marketplace** (external engineers as paid intermediaries):

*For complete Facilitator schema, see [schemas/facilitator.json](./schemas/facilitator.json)*

---