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.7 KiB

Raw Blame History

Resources API

API endpoints for managing resource flows and exchanges.

Resource Flow Object

{
  "id": "uuid-string",
  "organization_id": "org-uuid",
  "site_id": "site-uuid",
  "resource_type": "waste_heat",
  "direction": "output",
  "name": "Boiler Waste Heat",
  "description": "Excess heat from industrial boiler system",
  "quantity": {
    "amount": 500.0,
    "unit": "kW",
    "precision_level": "measured"
  },
  "temporal_profile": {
    "pattern": "continuous",
    "availability_hours_per_week": 168,
    "peak_hours": ["06:00-22:00"],
    "seasonal_variation": "stable"
  },
  "quality": {
    "temperature_range": {
      "min_celsius": 70.0,
      "max_celsius": 90.0
    },
    "pressure_range": {
      "min_bar": 1.0,
      "max_bar": 3.0
    },
    "purity_pct": 95.0,
    "contamination_levels": {
      "heavy_metals_mg_kg": 50.0,
      "organic_compounds_mg_kg": 100.0
    },
    "ph_range": {
      "min": 6.0,
      "max": 8.0
    },
    "viscosity_cp": 1.0,
    "particle_size_microns": 10.0
  },
  "pricing": {
    "base_price_per_unit": 0.10,
    "currency": "EUR",
    "billing_cycle": "monthly",
    "volume_pricing_tiers": [
      {
        "min_volume": 0,
        "max_volume": 1000,
        "price_per_unit": 0.10,
        "discount_pct": 0
      },
      {
        "min_volume": 1000,
        "price_per_unit": 0.08,
        "discount_pct": 20
      }
    ]
  },
  "logistics": {
    "transportation_required": true,
    "preferred_methods": ["piping", "truck"],
    "maximum_transport_distance_km": 50.0,
    "storage_requirements": {
      "temperature_controlled": false,
      "special_containers": false,
      "shelf_life_days": 30
    }
  },
  "environmental_impact": {
    "carbon_footprint_kg_co2_eq": 0.5,
    "water_usage_liters": 2.0,
    "energy_consumption_kwh": 0.1,
    "waste_generation_kg": 0.05,
    "emissions_by_type": {
      "CO2": 0.4,
      "NOx": 0.01,
      "SO2": 0.005
    },
    "renewable_energy_pct": 0.0,
    "circularity_score": 0.8
  },
  "performance_metrics": {
    "average_efficiency_pct": 85.0,
    "peak_performance_value": 600.0,
    "degradation_rate_pct_year": 2.0,
    "maintenance_interval_days": 90,
    "expected_lifespan_years": 15.0,
    "reliability_score": 0.95
  },
  "reliability_history": [
    {
      "date": "2025-01-01",
      "uptime_pct": 98.5,
      "outages_count": 2,
      "total_downtime_hours": 8.5
    }
  ],
  "certifications": ["ISO9001", "ISO14001"],
  "regulatory_requirements": {
    "permits_required": ["waste_disposal_permit"],
    "compliance_standards": ["REACH", "RoHS"],
    "monitoring_requirements": ["temperature", "flow_rate"]
  },
  "source_type": "device",
  "data_source": "SCADA_system",
  "last_updated": "2025-01-15T10:30:00Z",
  "verification_status": "verified",
  "tags": ["industrial", "continuous", "high_temperature"],
  "metadata": {
    "equipment_id": "BLR-001",
    "process_type": "steam_generation",
    "installation_date": "2020-03-15"
  }
}

Resource Types

Type	Description	Typical Units
`waste_heat`	Thermal waste heat	kW, MW
`excess_electricity`	Surplus electrical power	kW, MWh
`industrial_waste`	Manufacturing byproducts	kg, tonnes
`water_waste`	Wastewater or process water	m³, liters
`byproducts`	Production byproducts	kg, m³
`cooling_water`	Excess cooling capacity	kW, m³
`compressed_air`	Surplus compressed air	m³/min, bar
`logistics`	Transportation capacity	tonne-km
`materials`	Recyclable materials	kg, tonnes
`service`	Service offerings	hours, units

Resource Directions

input: Resource consumption (demand)
output: Resource production (supply)

Precision Levels

rough: Estimated values (±50%)
estimated: Calculated values (±25%)
measured: Sensor/monitored values (±5%)

Supply Patterns

continuous: 24/7 availability
batch: Periodic production
seasonal: Seasonal availability
on_demand: Available when requested
irregular: Unpredictable availability

Source Types

declared: Self-reported by organization
device: From IoT sensors/SCADA systems
calculated: Derived from other data sources

API Endpoints

List Resources

GET /api/v1/resources

Query Parameters:

organization_id (string, optional): Filter by organization
site_id (string, optional): Filter by site
resource_type (string, optional): Filter by resource type
direction (string, optional): Filter by direction (input/output)
limit (int, optional): Maximum results (default: 50)

Response:

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

Get Resource by ID

GET /api/v1/resources/{id}

Response: Single ResourceFlow object

Get Resources by Site

GET /api/v1/resources/site/{siteId}

Response: Array of ResourceFlow objects for the site

Get Resources by Organization

GET /api/v1/resources/organization/{organizationId}

Response: Array of ResourceFlow objects for the organization

Create Resource Flow

POST /api/v1/resources

Request Body: Complete ResourceFlow object

Required Fields:

organization_id
resource_type
direction
quantity.amount
quantity.unit

Response: Created ResourceFlow object

Update Resource Flow

PUT /api/v1/resources/{id}

Request Body: Partial ResourceFlow object

Response: Updated ResourceFlow object

Delete Resource Flow

DELETE /api/v1/resources/{id}

Response:

{
  "message": "Resource flow deleted successfully"
}

Quantity Specifications

Unit Standards

Energy:

W, kW, MW (power)
Wh, kWh, MWh (energy)

Mass:

g, kg, tonne, tonnes

Volume:

ml, liter, liters, m³, m3

Flow Rates:

m³/h, m³/day, kg/h, kg/day

Temporal Units

per_second
per_minute
per_hour
per_day
per_week
per_month
per_year
continuous

Quality Parameters

Temperature Resources

{
  "temperature_range": {
    "min_celsius": 70.0,
    "max_celsius": 90.0
  },
  "pressure_range": {
    "min_bar": 1.0,
    "max_bar": 3.0
  }
}

Material Resources

{
  "purity_pct": 95.0,
  "contamination_levels": {
    "heavy_metals_mg_kg": 50.0,
    "organic_compounds_mg_kg": 100.0
  },
  "particle_size_microns": 10.0,
  "moisture_pct": 5.0
}

Water Resources

{
  "ph_range": {
    "min": 6.0,
    "max": 8.0
  },
  "conductivity_us_cm": 500.0,
  "turbidity_ntu": 2.0,
  "dissolved_oxygen_mg_l": 8.0
}

Pricing Models

Volume-Based Pricing

{
  "volume_pricing_tiers": [
    {
      "min_volume": 0,
      "max_volume": 1000,
      "price_per_unit": 0.10,
      "discount_pct": 0
    },
    {
      "min_volume": 1000,
      "max_volume": 5000,
      "price_per_unit": 0.08,
      "discount_pct": 20
    },
    {
      "min_volume": 5000,
      "price_per_unit": 0.06,
      "discount_pct": 40
    }
  ]
}

Time-Based Pricing

{
  "time_based_pricing": {
    "peak_hours_rate": 0.15,
    "off_peak_hours_rate": 0.08,
    "seasonal_adjustments": {
      "winter_multiplier": 1.2,
      "summer_multiplier": 0.9
    }
  }
}

Logistics Requirements

Transportation Methods

piping: Fixed infrastructure for fluids
truck: Road transportation (flexible)
rail: Rail transportation (bulk)
ship: Water transportation
conveyor: Mechanical transport systems

Storage Requirements

{
  "temperature_controlled": true,
  "special_containers": false,
  "hazard_class": "non_hazardous",
  "shelf_life_days": 30,
  "special_handling": ["flammable"]
}

Environmental Impact Tracking

Carbon Accounting

{
  "carbon_footprint_kg_co2_eq": 0.5,
  "scope_classification": "Scope 1",
  "calculation_method": "IPCC Guidelines",
  "baseline_year": 2020,
  "reduction_potential_pct": 75.0
}

Water Footprint

{
  "water_usage_liters": 2.0,
  "water_stress_impact": "medium",
  "recycling_rate_pct": 60.0,
  "water_quality_impact": "neutral"
}

Performance Monitoring

Reliability Metrics

{
  "uptime_pct": 98.5,
  "mean_time_between_failures_days": 45.0,
  "mean_time_to_repair_hours": 4.0,
  "availability_score": 0.985
}

Efficiency Tracking

{
  "energy_efficiency_ratio": 0.85,
  "resource_recovery_rate_pct": 92.0,
  "waste_reduction_pct": 75.0
}

Regulatory Compliance

Permit Requirements

{
  "permits_required": [
    "waste_disposal_permit",
    "environmental_impact_assessment",
    "transport_permit"
  ],
  "permit_status": "active",
  "next_renewal_date": "2025-12-31"
}

Standards Compliance

{
  "compliance_standards": ["REACH", "RoHS", "ISO14001"],
  "certification_status": "certified",
  "last_audit_date": "2024-06-15",
  "next_audit_date": "2025-06-15"
}

Data Validation Rules

Quantity Validation

Must be positive number
Unit must be valid for resource type
Precision level must match data source quality

Quality Parameters

Temperature ranges must be physically possible
Purity percentages must be 0-100
pH values must be 0-14

Pricing Validation

Prices must be non-negative
Volume tiers must be sequential
Currency codes must be valid ISO 4217

Error Responses

Validation Errors

{
  "error": "Resource validation failed",
  "details": {
    "quantity.amount": "Amount must be positive",
    "quality.temperature_range": "Temperature range invalid"
  }
}

Resource Not Found

{
  "error": "Resource flow not found"
}

Permission Denied

{
  "error": "Insufficient permissions to modify resource"
}

9.7 KiB Raw Blame History

Resources API

Resource Flow Object

Resource Types

Resource Directions

Precision Levels

Supply Patterns

Source Types

API Endpoints

List Resources

Get Resource by ID

Get Resources by Site

Get Resources by Organization

Create Resource Flow

Update Resource Flow

Delete Resource Flow

Quantity Specifications

Unit Standards

Temporal Units

Quality Parameters

Temperature Resources

Material Resources

Water Resources

Pricing Models

Volume-Based Pricing

Time-Based Pricing

Logistics Requirements

Transportation Methods

Storage Requirements

Environmental Impact Tracking

Carbon Accounting

Water Footprint

Performance Monitoring

Reliability Metrics

Efficiency Tracking

Regulatory Compliance

Permit Requirements

Standards Compliance

Data Validation Rules

Quantity Validation

Quality Parameters

Pricing Validation

Error Responses

Validation Errors

Resource Not Found

Permission Denied

9.7 KiB

Raw Blame History