mirror of https://github.com/SamyRai/turash.git synced 2025-12-26 23:01:33 +00:00

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

9.2 KiB

Raw Blame History

Organizations API

Complete API documentation for organization management endpoints.

Organization Object

{
  "id": "uuid-string",
  "name": "Organization Name",
  "subtype": "business",
  "sector": "Manufacturing",
  "description": "Detailed company description",
  "logoUrl": "https://api.turash.com/static/images/logos/uuid.jpg",
  "galleryImages": [
    "https://api.turash.com/static/images/gallery/uuid1.jpg",
    "https://api.turash.com/static/images/gallery/uuid2.jpg"
  ],
  "website": "https://company.com",
  "address": "123 Industrial Street, City, Country",
  "latitude": 55.7558,
  "longitude": 37.6176,
  "legalForm": "LLC",
  "primaryContactEmail": "contact@company.com",
  "primaryContactPhone": "+7-495-123-45-67",
  "industrialSector": "C20",
  "companySize": 150,
  "yearsOperation": 10,
  "supplyChainRole": "manufacturer",
  "certifications": ["ISO9001", "ISO14001"],
  "businessFocus": ["sustainability", "innovation"],
  "strategicVision": "Vision statement",
  "driversBarriers": "Key drivers and barriers",
  "readinessMaturity": 4,
  "trustScore": 0.85,
  "technicalExpertise": ["process_optimization", "waste_management"],
  "availableTechnology": ["heat_recovery", "recycling"],
  "managementSystems": ["ERP", "MES"],
  "sellsProducts": [
    {
      "name": "Industrial Waste Product",
      "category": "Waste Materials",
      "description": "Recyclable industrial waste",
      "quantity": 1000,
      "unit": "kg/month",
      "pricePerUnit": 0.50,
      "quality": {
        "purity": "95%",
        "contamination": ["heavy_metals", "organic_compounds"]
      }
    }
  ],
  "offersServices": [
    {
      "name": "Waste Treatment Service",
      "category": "Environmental Services",
      "description": "Industrial waste treatment",
      "capacity": 5000,
      "unit": "kg/day",
      "pricing": {
        "basePrice": 1000,
        "currency": "EUR",
        "billingCycle": "monthly",
        "volumePricingTiers": [
          {
            "minVolume": 0,
            "maxVolume": 1000,
            "pricePerUnit": 0.20,
            "discountPct": 0
          },
          {
            "minVolume": 1000,
            "pricePerUnit": 0.15,
            "discountPct": 25
          }
        ]
      }
    }
  ],
  "needsServices": [
    {
      "category": "Transportation",
      "description": "Need logistics support for waste transport",
      "urgency": "high",
      "budget": {
        "minAmount": 5000,
        "maxAmount": 15000,
        "currency": "EUR",
        "frequency": "monthly"
      }
    }
  ],
  "yearBuilt": "1995",
  "builderOwner": "Original Construction Company",
  "architect": "Architect Name",
  "originalPurpose": "Manufacturing facility",
  "currentUse": "Chemical manufacturing",
  "style": "Industrial",
  "materials": "Steel and concrete",
  "storeys": 3,
  "heritageStatus": "Not protected",
  "verified": true,
  "notes": "Additional notes",
  "sources": ["Company website", "Industry database"],
  "trustNetwork": ["partner-org-uuid"],
  "existingSymbioticRelationships": ["supplier-uuid"],
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Organization Subtypes

business: Commercial companies and enterprises
facility: Industrial facilities and plants
cultural: Cultural institutions and venues
religious: Religious organizations
government: Government entities and agencies
educational: Schools, universities, research institutions
healthcare: Hospitals, clinics, medical facilities
infrastructure: Utility providers, transportation
other: Other organization types

Legal Forms

LLC: Limited Liability Company
corporation: Corporation
partnership: Partnership
sole_proprietorship: Sole Proprietorship
GmbH: German GmbH
UG: German UG (haftungsbeschränkt)
AG: German AG (Aktiengesellschaft)

Supply Chain Roles

manufacturer: Produces goods
supplier: Supplies materials/components
distributor: Distributes products
consumer: Consumes products/services

API Endpoints

List Organizations

GET /api/v1/organizations

Query Parameters:

limit (int, optional): Maximum results (default: 50, max: 100)
offset (int, optional): Pagination offset (default: 0)
sector (string, optional): Filter by sector
subtype (string, optional): Filter by organization subtype
verified (boolean, optional): Filter by verification status
min_trust_score (float, optional): Minimum trust score (0.0-1.0)
max_distance_km (float, optional): Filter by distance from coordinates
lat (float, optional): Latitude for distance filtering
lng (float, optional): Longitude for distance filtering

Response:

{
  "data": [Organization],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Get Organization by ID

GET /api/v1/organizations/{id}

Response: Single Organization object

Search Organizations

GET /api/v1/organizations/search

Query Parameters:

q (string, required): Search query (searches name, description, sector)
sector (string, optional): Filter by sector
subtype (string, optional): Filter by subtype
limit (int, optional): Maximum results (default: 20)

Response: Array of matching Organization objects

Search Suggestions

GET /api/v1/organizations/suggestions

Query Parameters:

q (string, required): Partial search query
limit (int, optional): Maximum suggestions (default: 10)

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Organization Name",
      "sector": "Manufacturing",
      "subtype": "business"
    }
  ]
}

Get Sector Statistics

GET /api/v1/organizations/sectors/stats

Response:

{
  "data": {
    "totalOrganizations": 1250,
    "sectors": {
      "Manufacturing": {
        "count": 450,
        "percentage": 36.0,
        "subtypes": {
          "business": 380,
          "facility": 70
        }
      }
    },
    "subtypes": {
      "business": 980,
      "facility": 200,
      "cultural": 50,
      "other": 20
    }
  }
}

Get Similar Organizations

GET /api/v1/organizations/{id}/similar

Query Parameters:

limit (int, optional): Maximum results (default: 10)

Response: Array of similar Organization objects

Get Organization Proposals

GET /api/v1/organizations/{id}/proposals

Response: Array of proposal objects related to the organization

Get Organization Resources

GET /api/v1/organizations/{id}/resources

Response: Array of resource flow objects associated with the organization

Get Direct Matches

GET /api/v1/organizations/{id}/matching/direct

Response: Array of direct matching opportunities

Create Organization

POST /api/v1/organizations

Request Body: Complete Organization object (see schema above)

Required Fields:

name
sector
subtype

Response: Created Organization object

Update Organization

PUT /api/v1/organizations/{id}

Request Body: Partial Organization object (only fields to update)

Response: Updated Organization object

Delete Organization

DELETE /api/v1/organizations/{id}

Response:

{
  "message": "Organization deleted successfully"
}

Image Upload Endpoints

Upload Logo

POST /api/v1/organizations/{id}/logo

Content-Type: multipart/form-data

Form Fields:

image (file, required): Image file (JPEG, PNG, max 5MB)

Response:

{
  "data": {
    "url": "https://api.turash.com/static/images/logos/uuid.jpg",
    "path": "/logos/uuid.jpg"
  },
  "message": "Logo uploaded successfully"
}

Upload Gallery Image

POST /api/v1/organizations/{id}/gallery

Content-Type: multipart/form-data

Form Fields:

image (file, required): Image file (JPEG, PNG, max 10MB)

Response:

{
  "data": {
    "url": "https://api.turash.com/static/images/gallery/uuid.jpg",
    "galleryImages": ["url1", "url2", "url3"]
  },
  "message": "Gallery image uploaded successfully"
}

Delete Gallery Image

DELETE /api/v1/organizations/{id}/gallery?url={imageUrl}

Query Parameters:

url (string, required): Full URL of image to delete

Response:

{
  "data": {
    "galleryImages": ["url1", "url2"]
  },
  "message": "Gallery image deleted successfully"
}

Data Validation Rules

Organization Name

Required
2-200 characters
Unique across all organizations

Geographic Coordinates

latitude: -90.0 to 90.0
longitude: -180.0 to 180.0

Trust Score

Range: 0.0 to 1.0
Represents reliability and reputation

Readiness Maturity

Range: 1 to 5
1: Unaware of industrial symbiosis
5: Actively engaged in multiple symbiotic relationships

Company Size

Must be positive integer
Represents number of employees

Years of Operation

Must be non-negative integer

Error Responses

Validation Errors

{
  "error": "Validation failed",
  "details": {
    "name": "Name is required",
    "latitude": "Latitude must be between -90 and 90"
  }
}

Not Found

{
  "error": "Organization not found"
}

Unauthorized

{
  "error": "Authentication required"
}

9.2 KiB Raw Blame History

Organizations API

Organization Object

Organization Subtypes

Legal Forms

Supply Chain Roles

API Endpoints

List Organizations

Get Organization by ID

Search Organizations

Search Suggestions

Get Sector Statistics

Get Similar Organizations

Get Organization Proposals

Get Organization Resources

Get Direct Matches

Create Organization

Update Organization

Delete Organization

Image Upload Endpoints

Upload Logo

Upload Gallery Image

Delete Gallery Image

Data Validation Rules

Organization Name

Geographic Coordinates

Trust Score

Readiness Maturity

Company Size

Years of Operation

Error Responses

Validation Errors

Not Found

Unauthorized

9.2 KiB

Raw Blame History