localgreenchain/docs/guides/transport-guide.md

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

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

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:

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

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

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

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

GET /api/transport/journey/plant-001

Response:

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

Get Environmental Impact

GET /api/transport/footprint/user-123

Response:

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

GET /api/transport/verify/abc123def456

QR Code Integration

Generate QR Data

GET /api/transport/qr/plant-001

Response:

{
  "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 - Complete grower workflow
• Consumer Guide - Consumer perspective
• Vertical Farm Guide - Indoor growing