vinnie/localgreenchain
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
localgreenchain/docs/api/vertical-farming-api.md
Claude 4111c3acf1
Add complete documentation suite for LocalGreenChain 
- Add guides: quick-start, installation, configuration, grower, consumer, transport, vertical-farm
- Add API references: REST, demand, vertical-farming
- Add concepts: blockchain, seasonal-planning, carbon-footprint
- Add architecture: data-flow, transport-tracking
- Add vertical-farming: environmental-control, automation, integration
- Add examples: seed-to-harvest, demand-driven-planting, vertical-farm-setup

Completes Agent_5 documentation tasks from AGENT_REPORT.md
2025-11-22 18:48:42 +00:00

8.9 KiB
Raw Blame History

Vertical Farming API Reference

Complete API reference for the LocalGreenChain Vertical Farming system.

Overview

The Vertical Farming API enables:

  • Farm registration and management
  • Zone configuration and monitoring
  • Crop batch lifecycle management
  • Environment tracking and alerts
  • Analytics and reporting

Farm Management

Register Farm

POST /api/vertical-farm/register
Content-Type: application/json

{
  "name": "Urban Greens VF",
  "ownerId": "owner-123",

  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "123 Industrial Blvd",
    "city": "Brooklyn",
    "country": "USA",
    "timezone": "America/New_York"
  },

  "specs": {
    "totalAreaSqm": 500,
    "growingAreaSqm": 400,
    "numberOfLevels": 4,
    "ceilingHeightM": 4,
    "totalGrowingPositions": 5000,
    "currentActivePlants": 0,
    "powerCapacityKw": 150,
    "waterStorageL": 10000,
    "backupPowerHours": 24,
    "certifications": ["gap", "local_food_safety"],
    "buildingType": "warehouse",
    "insulation": "high_efficiency"
  },

  "automationLevel": "semi_automated"
}

Response:

{
  "success": true,
  "data": {
    "id": "farm-abc123",
    "name": "Urban Greens VF",
    "status": "operational",
    "createdAt": "2024-06-01T10:00:00Z"
  }
}

Get Farm

GET /api/vertical-farm/{farmId}

Update Farm

PUT /api/vertical-farm/{farmId}
Content-Type: application/json

{
  "status": "maintenance",
  "specs": {
    "currentActivePlants": 4500
  }
}

List User Farms

GET /api/vertical-farm?ownerId=owner-123

Zone Management

Create Zone

POST /api/vertical-farm/{farmId}/zones
Content-Type: application/json

{
  "name": "Zone A - Leafy Greens",
  "level": 1,
  "areaSqm": 100,
  "lengthM": 20,
  "widthM": 5,
  "growingMethod": "NFT",
  "plantPositions": 1200,

  "environmentTargets": {
    "temperatureC": { "min": 18, "max": 24, "target": 21 },
    "humidityPercent": { "min": 55, "max": 75, "target": 65 },
    "co2Ppm": { "min": 800, "max": 1400, "target": 1000 },
    "lightPpfd": { "min": 200, "max": 400, "target": 300 },
    "lightHours": 16,
    "nutrientEc": { "min": 1.2, "max": 1.8, "target": 1.5 },
    "nutrientPh": { "min": 5.5, "max": 6.5, "target": 6.0 },
    "waterTempC": { "min": 18, "max": 22, "target": 20 }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "zone-abc123",
    "name": "Zone A - Leafy Greens",
    "status": "empty"
  }
}

Get Zones

GET /api/vertical-farm/{farmId}/zones

Get Zone Details

GET /api/vertical-farm/{farmId}/zones/{zoneId}

Update Zone

PUT /api/vertical-farm/{farmId}/zones/{zoneId}
Content-Type: application/json

{
  "status": "preparing",
  "environmentTargets": { ... }
}

Growing Recipes

List Recipes

GET /api/vertical-farm/recipes

Response:

{
  "success": true,
  "data": [
    {
      "id": "recipe-lettuce-butterhead",
      "name": "Butterhead Lettuce - Fast Cycle",
      "cropType": "lettuce",
      "variety": "butterhead",
      "version": "1.0",
      "expectedDays": 35,
      "expectedYieldGrams": 180,
      "expectedYieldPerSqm": 4000,
      "requirements": {
        "positions": 1,
        "zoneType": "NFT",
        "minimumPpfd": 200,
        "idealTemperatureC": 21
      },
      "source": "internal",
      "rating": 4.5,
      "timesUsed": 156
    }
  ]
}

Get Recipe Details

GET /api/vertical-farm/recipes/{recipeId}

Response includes full stage definitions:

{
  "success": true,
  "data": {
    "id": "recipe-lettuce-butterhead",
    "stages": [
      {
        "name": "Germination",
        "daysStart": 0,
        "daysEnd": 3,
        "temperature": { "day": 20, "night": 18 },
        "humidity": { "day": 80, "night": 85 },
        "co2Ppm": 800,
        "lightHours": 18,
        "lightPpfd": 150,
        "nutrientRecipeId": "nutrient-seedling",
        "targetEc": 0.8,
        "targetPh": 6.0,
        "actions": []
      }
    ]
  }
}

Add Custom Recipe

POST /api/vertical-farm/recipes
Content-Type: application/json

{
  "name": "Custom Lettuce - High Yield",
  "cropType": "lettuce",
  "variety": "romaine",
  "stages": [ ... ],
  "expectedDays": 42,
  "expectedYieldGrams": 220
}

Crop Batches

Start Batch

POST /api/vertical-farm/batch/start
Content-Type: application/json

{
  "farmId": "farm-abc123",
  "zoneId": "zone-abc123",
  "recipeId": "recipe-lettuce-butterhead",
  "seedBatchId": "seeds-lettuce-001",
  "plantCount": 200
}

Response:

{
  "success": true,
  "data": {
    "id": "batch-abc123",
    "farmId": "farm-abc123",
    "zoneId": "zone-abc123",
    "cropType": "lettuce",
    "plantCount": 200,
    "plantingDate": "2024-06-01T10:00:00Z",
    "expectedHarvestDate": "2024-07-06T10:00:00Z",
    "expectedYieldKg": 36,
    "currentStage": "Germination",
    "currentDay": 0,
    "healthScore": 100,
    "status": "germinating",
    "plantIds": ["batch-abc123-plant-0", "..."]
  }
}

Get Batch

GET /api/vertical-farm/batch/{batchId}

List Batches

GET /api/vertical-farm/batch?farmId=farm-abc123&status=growing

Update Batch Progress

POST /api/vertical-farm/batch/{batchId}/progress

This recalculates current day, stage, and updates environment targets.

Environment Tracking

Record Environment

PUT /api/vertical-farm/batch/{batchId}/environment
Content-Type: application/json

{
  "timestamp": "2024-06-15T12:00:00Z",
  "temperatureC": 21.5,
  "humidityPercent": 68,
  "co2Ppm": 1050,
  "vpd": 0.85,
  "ppfd": 295,
  "dli": 17.0,
  "waterTempC": 19.5,
  "ec": 1.55,
  "ph": 6.1,
  "dissolvedOxygenPpm": 8.2,
  "airflowMs": 0.5
}

Response includes any triggered alerts:

{
  "success": true,
  "data": {
    "recorded": true,
    "alerts": [
      {
        "parameter": "temperature",
        "type": "high",
        "value": 21.5,
        "threshold": 21,
        "timestamp": "2024-06-15T12:00:00Z",
        "acknowledged": false
      }
    ],
    "healthScore": 99
  }
}

Get Environment History

GET /api/vertical-farm/batch/{batchId}/environment
  ?from=2024-06-01T00:00:00Z
  &to=2024-06-15T00:00:00Z

Acknowledge Alert

POST /api/vertical-farm/batch/{batchId}/alerts/{alertId}/acknowledge

Harvest

Complete Harvest

POST /api/vertical-farm/batch/{batchId}/harvest
Content-Type: application/json

{
  "actualYieldKg": 38.5,
  "qualityGrade": "A",
  "notes": "Excellent crop, exceeded expectations"
}

Response:

{
  "success": true,
  "data": {
    "batchId": "batch-abc123",
    "status": "completed",
    "actualYieldKg": 38.5,
    "expectedYieldKg": 36,
    "yieldVariance": 6.9,
    "qualityGrade": "A",
    "actualHarvestDate": "2024-07-06T14:00:00Z",
    "cycleLength": 35
  }
}

Analytics

Get Farm Analytics

GET /api/vertical-farm/{farmId}/analytics?period=30

Query Parameters:

  • period: Number of days to analyze (default: 30)

Response:

{
  "success": true,
  "data": {
    "farmId": "farm-abc123",
    "generatedAt": "2024-07-01T10:00:00Z",
    "period": "30 days",

    "production": {
      "totalYieldKg": 450.5,
      "yieldPerSqmPerYear": 4107.5,
      "cropCyclesCompleted": 12,
      "averageCyclesDays": 28.5
    },

    "quality": {
      "averageQualityScore": 92.3,
      "gradeAPercent": 85,
      "wastagePercent": 4.5
    },

    "efficiency": {
      "cropSuccessRate": 98,
      "spaceUtilization": 88,
      "laborHoursPerKg": 0.3
    },

    "financial": {
      "revenueUsd": 9010,
      "costUsd": 4505,
      "profitMarginPercent": 50,
      "revenuePerSqm": 22.53
    },

    "environmental": {
      "carbonFootprintKgPerKg": 0.28,
      "waterUseLPerKg": 4.5,
      "energyUseKwhPerKg": 15.2
    },

    "topCropsByYield": [
      { "crop": "lettuce", "yieldKg": 250.2 },
      { "crop": "basil", "yieldKg": 120.5 }
    ],

    "topCropsByRevenue": [
      { "crop": "basil", "revenueUsd": 4820 },
      { "crop": "lettuce", "revenueUsd": 3750 }
    ],

    "topCropsByEfficiency": [
      { "crop": "microgreens", "efficiencyScore": 95 },
      { "crop": "lettuce", "efficiencyScore": 92 }
    ]
  }
}

Enums

Farm Status

type FarmStatus = 'offline' | 'starting' | 'operational' | 'maintenance' | 'emergency';

Zone Status

type ZoneStatus = 'empty' | 'preparing' | 'planted' | 'growing' | 'harvesting' | 'cleaning';

Growing Method

type GrowingMethod = 'NFT' | 'DWC' | 'ebb_flow' | 'aeroponics' | 'vertical_towers' | 'rack_system';

Batch Status

type BatchStatus = 'germinating' | 'growing' | 'ready' | 'harvesting' | 'completed' | 'failed';

Alert Type

type AlertType = 'low' | 'high' | 'critical_low' | 'critical_high' | 'sensor_fault';

Quality Grade

type QualityGrade = 'A' | 'B' | 'C' | 'processing';