# Transport Guide

Complete guide to recording and tracking transport events in LocalGreenChain.

## Transport Event Types

LocalGreenChain tracks 9 types of transport events covering the complete seed-to-seed lifecycle:

| Event Type | Description | When to Use |
|------------|-------------|-------------|
| `seed_acquisition` | Receiving seeds from any source | Purchasing, trading, or harvesting seeds |
| `planting` | Planting seeds or transplanting | Starting new plants |
| `growing_transport` | Moving plants during growth | Transplanting, hardening off |
| `harvest` | Collecting produce from plants | Harvest day |
| `processing` | Processing harvested produce | Washing, cutting, packaging |
| `distribution` | Moving to distribution points | To markets, hubs, restaurants |
| `consumer_delivery` | Final delivery to consumer | Last mile delivery |
| `seed_saving` | Collecting seeds from plants | End of growing cycle |
| `seed_sharing` | Sharing seeds with others | Trading, gifting seeds |

## Recording Transport Events

### Seed Acquisition

```typescript
POST /api/transport/seed-acquisition

{
  // Required fields
  seedBatchId: "seeds-tomato-2024-001",
  sourceType: "purchase",  // seed_bank, previous_harvest, trade, purchase, wild_collected, gift
  species: "Solanum lycopersicum",
  quantity: 500,
  quantityUnit: "seeds",
  generation: 1,

  // Location (from → to)
  fromLocation: {
    latitude: 38.9072,
    longitude: -77.0369,
    locationType: "seed_bank",
    facilityName: "Heritage Seeds"
  },
  toLocation: {
    latitude: 40.7128,
    longitude: -74.0060,
    locationType: "farm",
    facilityName: "Green Valley Farm"
  },

  // Transport details
  transportMethod: "local_delivery",
  durationMinutes: 120,

  // Optional details
  variety: "Cherokee Purple",
  certifications: ["organic", "heirloom"],
  germinationRate: 92,
  harvestDate: "2023-10-15",
  geneticLineageId: "lineage-abc123"
}
```

### Planting Event

```typescript
POST /api/transport/planting

{
  seedBatchId: "seeds-tomato-2024-001",
  plantIds: ["plant-001", "plant-002"],  // Can be auto-generated
  quantityPlanted: 50,
  plantingMethod: "transplant",  // direct_sow, transplant, indoor_start, hydroponic, aeroponic
  growingEnvironment: "greenhouse",  // outdoor, greenhouse, indoor, vertical_farm

  fromLocation: {
    latitude: 40.7128,
    longitude: -74.0060,
    locationType: "greenhouse",
    facilityName: "Seed Starting House"
  },
  toLocation: {
    latitude: 40.7130,
    longitude: -74.0065,
    locationType: "greenhouse",
    facilityName: "Growing Greenhouse"
  },

  expectedHarvestDate: "2024-08-15",
  sowingDepth: 6,  // mm
  spacing: 60  // cm
}
```

### Growing Transport

For transplanting or moving plants:

```typescript
POST /api/transport/growing

{
  plantIds: ["plant-001", "plant-002"],
  reason: "transplant",  // transplant, relocation, hardening_off, seasonal_move, upgrade_facility
  plantStage: "seedling",  // seed, germinating, seedling, vegetative, flowering, fruiting, mature
  handlingMethod: "potted",  // bare_root, potted, root_ball, hydroponic_transfer

  rootDisturbance: "minimal",  // none, minimal, moderate, significant
  acclimatizationRequired: true,
  acclimatizationDays: 7,

  fromLocation: { ... },
  toLocation: { ... },

  transportMethod: "walking",
  environmentalConditions: {
    temperatureMin: 15,
    temperatureMax: 22,
    temperatureAvg: 18,
    humidityMin: 60,
    humidityMax: 80,
    humidityAvg: 70,
    lightExposure: "ambient"
  }
}
```

### Harvest Event

```typescript
POST /api/transport/harvest

{
  plantIds: ["plant-001", "plant-002"],
  harvestBatchId: "harvest-2024-001",
  harvestType: "full",  // full, partial, continuous, selective
  produceType: "tomatoes",

  // Weights
  grossWeight: 50,
  netWeight: 47,
  weightUnit: "kg",
  itemCount: 200,

  // Quality
  qualityGrade: "A",  // A, B, C, processing
  qualityNotes: "Excellent color and firmness",

  // Storage requirements
  packagingType: "cardboard_flat",
  temperatureRequired: {
    min: 10,
    max: 15,
    optimal: 12,
    unit: "celsius"
  },
  shelfLifeHours: 168,

  // Seed saving
  seedsSaved: true,
  seedBatchIdCreated: "seeds-tomato-2024-002",

  fromLocation: { ... },
  toLocation: { ... }
}
```

### Distribution Event

```typescript
POST /api/transport/distribution

{
  batchIds: ["harvest-2024-001"],
  destinationType: "market",  // consumer, market, restaurant, processor, distributor, vertical_farm
  customerType: "business",  // individual, business, cooperative, institution

  orderId: "order-456",
  deliveryWindow: {
    start: "2024-08-02T06:00:00Z",
    end: "2024-08-02T08:00:00Z"
  },
  deliveryAttempts: 1,
  handoffVerified: true,
  recipientName: "Brooklyn Farmers Market",

  transportMethod: "electric_vehicle",
  fromLocation: { ... },
  toLocation: { ... }
}
```

### Seed Saving Event

```typescript
POST /api/transport/seed-saving

{
  parentPlantIds: ["plant-001", "plant-005"],
  newSeedBatchId: "seeds-tomato-2024-002",

  // Collection details
  collectionMethod: "wet_seed",  // dry_seed, wet_seed, fermentation, threshing
  seedCount: 250,
  seedWeight: 15,
  seedWeightUnit: "grams",

  // Quality testing
  viabilityTestDate: "2024-08-20",
  germinationRate: 94,
  purityPercentage: 98,

  // Storage
  storageConditions: {
    temperature: 4,
    humidity: 30,
    lightExposure: "dark",
    containerType: "vacuum_sealed",
    desiccant: true,
    estimatedViability: 5  // years
  },
  storageLocationId: "storage-vault-001",

  // Lineage
  newGenerationNumber: 2,
  geneticNotes: "Selected for disease resistance and flavor",

  // Sharing
  availableForSharing: true,
  sharingTerms: "trade"
}
```

## Carbon Footprint Calculation

### Carbon Factors by Transport Method

| Method | kg CO2 per km per kg |
|--------|---------------------|
| walking | 0 |
| bicycle | 0 |
| electric_vehicle | 0.02 |
| hybrid_vehicle | 0.08 |
| gasoline_vehicle | 0.12 |
| diesel_truck | 0.15 |
| electric_truck | 0.03 |
| refrigerated_truck | 0.25 |
| rail | 0.01 |
| ship | 0.008 |
| air | 0.5 |
| drone | 0.01 |
| local_delivery | 0.05 |
| customer_pickup | 0.1 |

### Calculation Formula

```
Carbon (kg CO2) = Factor × Distance (km) × Weight (kg)
```

### Example

```
Tomatoes: 20 kg
Distance: 25 km
Method: electric_vehicle (factor: 0.02)

Carbon = 0.02 × 25 × 20 = 10 kg CO2
```

## Querying Transport Data

### Get Plant Journey

```typescript
GET /api/transport/journey/plant-001
```

Response:

```json
{
  "plantId": "plant-001",
  "seedBatchOrigin": "seeds-tomato-2024-001",
  "currentStage": "harvesting",
  "events": [...],
  "totalFoodMiles": 45,
  "totalCarbonKg": 2.5,
  "daysGrowing": 85,
  "generation": 1,
  "ancestorPlantIds": []
}
```

### Get Environmental Impact

```typescript
GET /api/transport/footprint/user-123
```

Response:

```json
{
  "totalCarbonKg": 45.5,
  "totalFoodMiles": 320,
  "carbonPerKgProduce": 0.18,
  "breakdownByMethod": {
    "electric_vehicle": { "distance": 200, "carbon": 20 },
    "walking": { "distance": 50, "carbon": 0 }
  },
  "comparisonToConventional": {
    "carbonSaved": 580,
    "milesSaved": 22500,
    "percentageReduction": 93
  }
}
```

### Verify Block

```typescript
GET /api/transport/verify/abc123def456
```

## QR Code Integration

### Generate QR Data

```typescript
GET /api/transport/qr/plant-001
```

Response:

```json
{
  "plantId": "plant-001",
  "blockchainAddress": "0x1234...",
  "quickLookupUrl": "https://localgreenchain.org/track/plant-001",
  "lineageHash": "sha256...",
  "currentCustodian": "grower-123",
  "lastEventType": "harvest",
  "verificationCode": "A1B2C3D4"
}
```

## Data Flow Diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                    TRANSPORT DATA FLOW                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌───────────┐                                                       │
│  │   SEED    │ seed_acquisition                                      │
│  │ ACQUISITION│────────────┐                                         │
│  └───────────┘             │                                         │
│       │                    ▼                                         │
│       │            ┌───────────────┐                                │
│       │            │  TRANSPORT    │                                │
│       │            │   CHAIN       │                                │
│       │            │  BLOCKCHAIN   │                                │
│       │            └───────┬───────┘                                │
│       ▼                    │                                         │
│  ┌───────────┐             │                                         │
│  │ PLANTING  │─────────────┤ planting                               │
│  └───────────┘             │                                         │
│       │                    │                                         │
│       ▼                    │                                         │
│  ┌───────────┐             │                                         │
│  │  GROWING  │─────────────┤ growing_transport                       │
│  │ TRANSPORT │             │                                         │
│  └───────────┘             │                                         │
│       │                    │                                         │
│       ▼                    │                                         │
│  ┌───────────┐             │                                         │
│  │  HARVEST  │─────────────┤ harvest                                 │
│  └───────────┘             │                                         │
│       │                    │                                         │
│       ├───────────────┐    │                                         │
│       ▼               ▼    │                                         │
│  ┌───────────┐  ┌─────────┐│                                         │
│  │DISTRIBUTE │  │  SEED   ││ distribution / seed_saving              │
│  │           │  │ SAVING  ││─────────────────────────────────────────│
│  └───────────┘  └─────────┘│                                         │
│       │              │     │                                         │
│       ▼              ▼     │                                         │
│  ┌───────────┐  ┌─────────┐│                                         │
│  │ CONSUMER  │  │  SEED   ││ consumer_delivery / seed_sharing        │
│  │ DELIVERY  │  │ SHARING ││                                         │
│  └───────────┘  └─────────┘│                                         │
│                      │     │                                         │
│                      └─────┼──→ Next Generation                      │
│                            │                                         │
└────────────────────────────┴─────────────────────────────────────────┘
```

## Best Practices

### Recording Events

1. **Be Timely** - Record events as they happen
2. **Be Accurate** - Correct coordinates and weights
3. **Be Complete** - Include all optional fields when possible
4. **Verify Locations** - Double-check GPS coordinates

### Transport Methods

1. **Choose Low Carbon** - Electric and human-powered preferred
2. **Combine Trips** - Reduce total distance
3. **Optimize Routes** - Shortest path reduces footprint
4. **Use Local First** - Minimize distance overall

### Quality Assurance

1. **Track Conditions** - Temperature, humidity, handling
2. **Note Issues** - Record any problems immediately
3. **Grade Honestly** - Accurate quality ratings
4. **Verify Handoffs** - Confirm custody changes

## Next Steps

- [Grower Guide](./grower-guide.md) - Complete grower workflow
- [Consumer Guide](./consumer-guide.md) - Consumer perspective
- [Vertical Farm Guide](./vertical-farm-guide.md) - Indoor growing