localgreenchain/docs/api/vertical-farming-api.md

# 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

```http
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:

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

### Get Farm

```http
GET /api/vertical-farm/{farmId}
```

### Update Farm

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

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

### List User Farms

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

---

## Zone Management

### Create Zone

```http
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:

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

### Get Zones

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

### Get Zone Details

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

### Update Zone

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

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

---

## Growing Recipes

### List Recipes

```http
GET /api/vertical-farm/recipes
```

Response:

```json
{
  "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

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

Response includes full stage definitions:

```json
{
  "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

```http
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

```http
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:

```json
{
  "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

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

### List Batches

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

### Update Batch Progress

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

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

---

## Environment Tracking

### Record Environment

```http
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:

```json
{
  "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

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

### Acknowledge Alert

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

---

## Harvest

### Complete Harvest

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

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

Response:

```json
{
  "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

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

Query Parameters:
- `period`: Number of days to analyze (default: 30)

Response:

```json
{
  "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

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

### Zone Status

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

### Growing Method

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

### Batch Status

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

### Alert Type

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

### Quality Grade

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