mukimovd/turash
1
0
Fork 0
mirror of https://github.com/SamyRai/turash.git synced 2025-12-26 23:01:33 +00:00
Code Issues 1 Actions Packages Projects Releases Wiki Activity
5d854419e1
turash/docs/concept/07_entity_relationships.md
Damir Mukimov 000eab4740
Major repository reorganization and missing backend endpoints implementation 
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)
2025-11-25 06:01:16 +01:00

3.5 KiB
Raw Blame History

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