# Vertical Farm Operator Guide

Complete guide for managing vertical farming operations with LocalGreenChain.

## Getting Started

### Register Your Farm

```typescript
POST /api/vertical-farm/register

{
  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,
    powerCapacityKw: 150,
    waterStorageL: 10000,
    backupPowerHours: 24,
    certifications: ["gap", "local_food_safety"],
    buildingType: "warehouse",
    insulation: "high_efficiency"
  },

  automationLevel: "semi_automated"
}
```

## Zone Configuration

### Create Growing Zones

```typescript
POST /api/vertical-farm/{farmId}/zones

{
  name: "Zone A - Leafy Greens",
  level: 1,
  areaSqm: 100,
  lengthM: 20,
  widthM: 5,
  growingMethod: "NFT",  // NFT, DWC, ebb_flow, aeroponics, vertical_towers, rack_system
  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 }
  }
}
```

### Zone Growing Methods

| Method | Best For | Water Use | Complexity |
|--------|----------|-----------|------------|
| NFT | Leafy greens, herbs | Low | Medium |
| DWC | Lettuce, basil | Medium | Low |
| Aeroponics | High-value crops | Very Low | High |
| Vertical Towers | Microgreens, strawberries | Low | Medium |
| Rack System | Microgreens | Low | Low |

## Growing Recipes

### Available Default Recipes

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

// Returns:
[
  {
    id: "recipe-lettuce-butterhead",
    name: "Butterhead Lettuce - Fast Cycle",
    expectedDays: 35,
    expectedYieldGrams: 180,
    expectedYieldPerSqm: 4000
  },
  {
    id: "recipe-basil-genovese",
    name: "Genovese Basil - Aromatic",
    expectedDays: 42,
    expectedYieldGrams: 120
  },
  {
    id: "recipe-microgreens-mix",
    name: "Microgreens Mix - Quick Turn",
    expectedDays: 14,
    expectedYieldGrams: 200
  }
]
```

### Recipe Stages

Each recipe defines stages with specific environment targets:

```typescript
// Lettuce example stages
[
  {
    name: "Germination",
    daysStart: 0,
    daysEnd: 3,
    temperature: { day: 20, night: 18 },
    humidity: { day: 80, night: 85 },
    co2Ppm: 800,
    lightHours: 18,
    lightPpfd: 150,
    targetEc: 0.8,
    targetPh: 6.0
  },
  {
    name: "Seedling",
    daysStart: 4,
    daysEnd: 10,
    temperature: { day: 21, night: 18 },
    humidity: { day: 70, night: 75 },
    lightPpfd: 200,
    targetEc: 1.2
  },
  {
    name: "Vegetative Growth",
    daysStart: 11,
    daysEnd: 28,
    lightPpfd: 300,
    targetEc: 1.6
  },
  {
    name: "Finishing",
    daysStart: 29,
    daysEnd: 35,
    lightPpfd: 250,
    targetEc: 1.2
  }
]
```

## Batch Management

### Start a Crop Batch

```typescript
POST /api/vertical-farm/batch/start

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

Response:

```json
{
  "batchId": "batch-abc123",
  "plantingDate": "2024-06-01T08:00:00Z",
  "expectedHarvestDate": "2024-07-06T08:00:00Z",
  "expectedYieldKg": 36,
  "plantIds": ["batch-abc123-plant-0", "..."]
}
```

### Monitor Batch Progress

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

Response:

```json
{
  "id": "batch-abc123",
  "currentDay": 15,
  "currentStage": "Vegetative Growth",
  "healthScore": 95,
  "status": "growing",
  "expectedHarvestDate": "2024-07-06",
  "issues": []
}
```

### Record Environment Readings

```typescript
PUT /api/vertical-farm/batch/{batchId}/environment

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

### Complete Harvest

```typescript
POST /api/vertical-farm/batch/{batchId}/harvest

{
  actualYieldKg: 38.5,
  qualityGrade: "A",
  notes: "Excellent crop, slight overperformance on yield"
}
```

## Environment Monitoring

### Alert Types

| Alert Type | Trigger | Severity |
|------------|---------|----------|
| `low` | Below minimum target | Warning |
| `high` | Above maximum target | Warning |
| `critical_low` | >5 below minimum | Critical |
| `critical_high` | >5 above maximum | Critical |
| `sensor_fault` | Sensor malfunction | Critical |

### Alert Response

```
┌─────────────────────────────────────────┐
│          ENVIRONMENT ALERT              │
├─────────────────────────────────────────┤
│                                         │
│  Parameter: Temperature                 │
│  Current: 28°C                          │
│  Target: 21°C (max: 24°C)               │
│  Type: HIGH                             │
│                                         │
│  Recommended Actions:                   │
│  1. Check HVAC system status            │
│  2. Verify ventilation is operational   │
│  3. Consider reducing light intensity   │
│  4. Check for blocked airflow           │
│                                         │
└─────────────────────────────────────────┘
```

### Health Score Impact

| Condition | Health Score Impact |
|-----------|---------------------|
| No alerts | No change |
| Minor alert | -1 point |
| Critical alert | -5 points |
| Extended critical | -10 points/day |

## Analytics

### View Farm Analytics

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

Response:

```json
{
  "farmId": "farm-123",
  "period": "30 days",

  "production": {
    "totalYieldKg": 450,
    "yieldPerSqmPerYear": 4100,
    "cropCyclesCompleted": 12,
    "averageCycleDays": 28
  },

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

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

  "financial": {
    "revenueUsd": 9000,
    "costUsd": 4500,
    "profitMarginPercent": 50,
    "revenuePerSqm": 22.50
  },

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

  "topCrops": {
    "byYield": ["lettuce", "basil", "microgreens"],
    "byRevenue": ["basil", "lettuce", "microgreens"],
    "byEfficiency": ["microgreens", "lettuce", "basil"]
  }
}
```

## Integration with Demand

### Respond to Demand Signals

```typescript
// Check regional demand
GET /api/demand/signal?lat=40.7128&lon=-74.0060&radius=25

// Find gaps you can fill
{
  "demandItems": [
    {
      "produceType": "lettuce",
      "gapKg": 50,
      "urgency": "this_week"
    }
  ]
}

// Start batch to fill demand
POST /api/vertical-farm/batch/start
{
  recipeId: "recipe-lettuce-butterhead",
  plantCount: 280  // To produce ~50kg
}
```

### Commit Supply

```typescript
POST /api/demand/supply

{
  produceType: "lettuce",
  variety: "butterhead",
  committedQuantityKg: 50,
  availableFrom: "2024-07-06",
  freshnessGuaranteeHours: 24,
  certifications: ["local_food_safety"]
}
```

## Blockchain Recording

Every batch creates transport events:

```
Seed Acquisition → Transport recorded
    ↓
Planting Event → Transport recorded
    ↓
Environment Logs → Stored with batch
    ↓
Harvest Event → Transport recorded
    ↓
Distribution → Transport recorded
```

Consumers can scan QR codes to see:
- Exact growing conditions
- Recipe used
- Environment history
- Seed lineage

## Best Practices

### For Operators

1. **Calibrate Regularly** - Sensors need weekly checks
2. **Follow Recipes** - Don't deviate without reason
3. **Log Everything** - Data enables optimization
4. **Respond to Alerts** - Quick action prevents losses
5. **Maintain Equipment** - Preventive > reactive

### For Efficiency

1. **Stagger Batches** - Continuous harvest flow
2. **Match Demand** - Check signals before planting
3. **Optimize Light** - Biggest energy cost
4. **Recirculate Water** - >95% reuse target
5. **Track KPIs** - What gets measured improves

### For Quality

1. **Start Clean** - Sanitize between batches
2. **Monitor Daily** - Catch issues early
3. **Harvest at Peak** - Don't over-mature
4. **Temperature Chain** - Maintain cold chain
5. **Grade Honestly** - Quality builds trust

## Troubleshooting

### Common Issues

| Issue | Possible Causes | Solutions |
|-------|-----------------|-----------|
| Low yield | Light too low, nutrients off | Check PPFD, EC levels |
| Tip burn | High EC, low calcium | Reduce nutrients, add CalMag |
| Bolting | Temperature too high | Reduce temp, increase airflow |
| Root rot | Low oxygen, warm water | Add air stones, cool reservoir |
| Slow growth | Low CO2, wrong temp | Check CO2 injection, adjust HVAC |

### Emergency Procedures

```
POWER FAILURE:
1. Backup power should engage automatically
2. Reduce light intensity if on battery
3. Maintain water circulation priority
4. Alert on-call technician

HVAC FAILURE:
1. Reduce light intensity immediately
2. Open vents for passive cooling
3. Mist plants if temperature rising
4. Call HVAC service

WATER LEAK:
1. Shut off main water supply
2. Isolate affected zone
3. Salvage plants if possible
4. Document for insurance
```

## Resource Efficiency

### Energy Optimization

| Component | % of Total | Optimization |
|-----------|------------|--------------|
| Lighting | 50-60% | LED efficacy, DLI optimization |
| HVAC | 20-30% | Heat pump, recovery systems |
| Pumps | 5-10% | Variable speed drives |
| Other | 5-10% | Automation, scheduling |

### Water Conservation

- Target: >95% water recirculation
- Condensate recovery from HVAC
- Rainwater collection if available
- RO reject water for non-crop use

## Next Steps

- [Grower Guide](./grower-guide.md) - Traditional growing
- [Transport Guide](./transport-guide.md) - Tracking transport
- [Consumer Guide](./consumer-guide.md) - Consumer perspective