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)
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
## 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)*
|
|
|
|
---
|
|
|
|
|