Add seed-to-seed transport tracking, demand forecasting, and vertical farming systems

This comprehensive update implements:

Transport Tracking System:
- Complete seed-to-seed lifecycle tracking with 9 event types
- TransportChain blockchain for immutable transport records
- Carbon footprint calculation per transport method
- Food miles tracking with Haversine distance calculation
- QR code generation for full traceability

Demand Forecasting System:
- Consumer preference registration and aggregation
- Regional demand signal generation
- Supply gap identification and market matching
- Grower planting recommendations with risk assessment
- Seasonal planning integration

Vertical Farming Module:
- Multi-zone facility management
- Environmental control systems (HVAC, CO2, humidity, lighting)
- Growing recipes with stage-based environment targets
- Crop batch tracking with health scoring
- Farm analytics generation

Documentation:
- Complete docs/ folder structure for Turborepo
- Seed-to-seed transport concept documentation
- Demand forecasting and seasonal planning guides
- System architecture and user blockchain design
- Transport API reference
- Vertical farming integration guide

Agent Report:
- AGENT_REPORT.md with 5 parallel agent tasks for continued development
- API routes implementation task
- UI components task
- Vertical farming pages task
- Testing suite task
- Documentation completion task

2025-11-22 18:23:08 +00:00

9.3 KiB

Raw Permalink Blame History

Transport API Reference

The Transport API enables seed-to-seed tracking of all plant movement and transformation events within the LocalGreenChain ecosystem.

Base URL

Development: http://localhost:3001/api/transport
Production:  https://api.localgreenchain.org/transport

Authentication

All transport endpoints require authentication:

Authorization: Bearer <user_token>
X-Wallet-Address: <wallet_address>

Endpoints

Record Seed Acquisition

Record the acquisition of seeds from any source.

POST /api/transport/seed-acquisition
Content-Type: application/json

{
  "seedBatchId": "batch-2025-001",
  "sourceType": "seed_bank",
  "species": "Solanum lycopersicum",
  "variety": "Cherokee Purple",
  "quantity": 50,
  "quantityUnit": "seeds",
  "geneticLineageId": "lineage-tomato-cp-001",
  "generation": 0,
  "fromLocation": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "locationType": "seed_bank",
    "facilityName": "Baker Creek Seeds"
  },
  "toLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "farm",
    "facilityName": "Urban Farm NYC"
  },
  "transportMethod": "local_delivery",
  "certifications": ["organic", "heirloom"]
}

Response:

{
  "success": true,
  "event": {
    "id": "evt-seed-acq-123",
    "timestamp": "2025-01-15T10:30:00Z",
    "eventType": "seed_acquisition",
    "status": "verified"
  },
  "block": {
    "index": 5,
    "hash": "0000abc123...",
    "carbonFootprintKg": 0.02,
    "foodMiles": 5.2
  }
}

Record Planting

Record when seeds are planted.

POST /api/transport/planting
Content-Type: application/json

{
  "seedBatchId": "batch-2025-001",
  "plantIds": ["plant-001", "plant-002", "plant-003"],
  "plantingMethod": "transplant",
  "quantityPlanted": 25,
  "growingEnvironment": "vertical_farm",
  "location": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "vertical_farm",
    "facilityName": "Urban Farm NYC"
  },
  "expectedHarvestDate": "2025-03-15T00:00:00Z"
}

Response:

{
  "success": true,
  "event": {
    "id": "evt-planting-124",
    "timestamp": "2025-01-20T08:00:00Z",
    "eventType": "planting",
    "plantIds": ["plant-001", "plant-002", "plant-003"]
  },
  "block": {
    "index": 6,
    "hash": "0000def456..."
  }
}

Record Growing Transport

Record plant movement during growing (transplanting, relocating).

POST /api/transport/growing
Content-Type: application/json

{
  "plantIds": ["plant-001", "plant-002"],
  "reason": "transplant",
  "plantStage": "seedling",
  "handlingMethod": "potted",
  "fromLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "greenhouse",
    "facilityName": "Seedling House A"
  },
  "toLocation": {
    "latitude": 40.7589,
    "longitude": -73.9852,
    "locationType": "vertical_farm",
    "facilityName": "Main Growing Tower"
  },
  "transportMethod": "walking",
  "rootDisturbance": "minimal",
  "acclimatizationRequired": true,
  "acclimatizationDays": 3
}

Record Harvest

Record harvest events with yield data.

POST /api/transport/harvest
Content-Type: application/json

{
  "plantIds": ["plant-001", "plant-002", "plant-003"],
  "harvestBatchId": "harvest-2025-050",
  "harvestType": "full",
  "produceType": "tomatoes",
  "grossWeight": 15.5,
  "netWeight": 14.2,
  "weightUnit": "kg",
  "qualityGrade": "A",
  "packagingType": "compostable_clamshell",
  "temperatureRequired": {
    "min": 10,
    "max": 15,
    "optimal": 12,
    "unit": "celsius"
  },
  "shelfLifeHours": 168,
  "seedsSaved": true,
  "seedBatchIdCreated": "batch-2025-002"
}

Response:

{
  "success": true,
  "event": {
    "id": "evt-harvest-125",
    "timestamp": "2025-03-15T06:00:00Z",
    "eventType": "harvest",
    "harvestBatchId": "harvest-2025-050",
    "netWeight": 14.2
  },
  "block": {
    "index": 25,
    "hash": "0000ghi789...",
    "carbonFootprintKg": 0.1
  },
  "seedBatch": {
    "id": "batch-2025-002",
    "parentPlants": ["plant-001", "plant-002", "plant-003"],
    "generation": 1
  }
}

Record Distribution

Record movement through distribution chain.

POST /api/transport/distribution
Content-Type: application/json

{
  "batchIds": ["harvest-2025-050"],
  "destinationType": "consumer",
  "fromLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "vertical_farm"
  },
  "toLocation": {
    "latitude": 40.7614,
    "longitude": -73.9776,
    "locationType": "consumer"
  },
  "transportMethod": "bicycle",
  "orderId": "order-2025-1234",
  "customerType": "individual",
  "deliveryWindow": {
    "start": "2025-03-15T14:00:00Z",
    "end": "2025-03-15T18:00:00Z"
  }
}

Record Seed Saving

Record seed saving from harvested plants.

POST /api/transport/seed-saving
Content-Type: application/json

{
  "parentPlantIds": ["plant-001", "plant-002"],
  "newSeedBatchId": "batch-2025-003",
  "collectionMethod": "fermentation",
  "seedCount": 200,
  "seedWeight": 15,
  "seedWeightUnit": "grams",
  "storageConditions": {
    "temperature": 10,
    "humidity": 40,
    "lightExposure": "dark",
    "containerType": "vacuum_sealed",
    "desiccant": true,
    "estimatedViability": 5
  },
  "newGenerationNumber": 2,
  "availableForSharing": true,
  "sharingTerms": "trade"
}

Record when seeds are shared with others.

POST /api/transport/seed-sharing
Content-Type: application/json

{
  "seedBatchId": "batch-2025-003",
  "quantityShared": 25,
  "quantityUnit": "seeds",
  "sharingType": "trade",
  "tradeDetails": "Traded for 25 basil seeds",
  "recipientId": "user-xyz-456",
  "fromLocation": {...},
  "toLocation": {...},
  "recipientAgreement": true,
  "growingCommitment": "Will grow and report back",
  "reportBackRequired": true
}

Query Endpoints

Get Plant Journey

Get complete transport history for a plant.

GET /api/transport/journey/:plantId

Response:

{
  "plantId": "plant-001",
  "seedBatchOrigin": "batch-2025-001",
  "currentCustodian": "user-abc-123",
  "currentLocation": {
    "latitude": 40.7614,
    "longitude": -73.9776,
    "locationType": "consumer"
  },
  "currentStage": "post_harvest",
  "events": [
    {
      "eventType": "seed_acquisition",
      "timestamp": "2025-01-15T10:30:00Z",
      "fromLocation": {...},
      "toLocation": {...}
    },
    {
      "eventType": "planting",
      "timestamp": "2025-01-20T08:00:00Z",
      ...
    },
    ...
  ],
  "totalFoodMiles": 12.5,
  "totalCarbonKg": 0.35,
  "daysInTransit": 2,
  "daysGrowing": 54,
  "generation": 1,
  "ancestorPlantIds": ["parent-plant-001"],
  "descendantSeedBatches": ["batch-2025-003"]
}

Get Environmental Impact

Get carbon footprint and food miles for a user.

GET /api/transport/footprint/:userId

Response:

{
  "totalCarbonKg": 15.5,
  "totalFoodMiles": 250,
  "carbonPerKgProduce": 0.25,
  "milesPerKgProduce": 4.0,
  "breakdownByMethod": {
    "bicycle": { "distance": 50, "carbon": 0 },
    "electric_vehicle": { "distance": 150, "carbon": 3.0 },
    "walking": { "distance": 50, "carbon": 0 }
  },
  "breakdownByEventType": {
    "seed_acquisition": { "count": 5, "carbon": 0.5 },
    "distribution": { "count": 50, "carbon": 10.0 },
    ...
  },
  "comparisonToConventional": {
    "carbonSaved": 140.5,
    "milesSaved": 74750,
    "percentageReduction": 90
  }
}

Verify Block

Verify a transport block's integrity.

GET /api/transport/verify/:blockHash

Response:

{
  "valid": true,
  "block": {
    "index": 25,
    "hash": "0000ghi789...",
    "previousHash": "0000fgh678...",
    "timestamp": "2025-03-15T06:00:00Z"
  },
  "chainValid": true,
  "crossReferences": [
    {
      "userId": "user-xyz-456",
      "blockIndex": 12,
      "type": "receiver",
      "verified": true
    }
  ]
}

Generate QR Code

Generate QR code data for a plant or batch.

GET /api/transport/qr/:plantId

Response:

{
  "plantId": "plant-001",
  "blockchainAddress": "0x1234567890abcdef...",
  "quickLookupUrl": "https://localgreenchain.org/track/plant-001",
  "lineageHash": "a1b2c3d4e5f6...",
  "currentCustodian": "user-abc-123",
  "lastEventType": "distribution",
  "lastEventTimestamp": "2025-03-15T14:30:00Z",
  "verificationCode": "A1B2C3D4",
  "qrCodeImage": "data:image/png;base64,..."
}

Error Codes

Code	Message	Description
400	Invalid request	Missing or invalid parameters
401	Unauthorized	Invalid or missing auth token
403	Forbidden	Not authorized for this resource
404	Not found	Plant/batch/block not found
409	Conflict	Duplicate event or chain conflict
422	Validation error	Data validation failed
500	Server error	Internal server error

Rate Limits

Endpoint Type	Limit	Window
Read (GET)	100	per minute
Write (POST)	20	per minute
Batch operations	5	per minute

Webhooks

Subscribe to transport events:

POST /api/transport/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["seed_acquisition", "harvest", "distribution"],
  "filters": {
    "plantIds": ["plant-001", "plant-002"],
    "userId": "user-abc-123"
  }
}

9.3 KiB Raw Permalink Blame History

Transport API Reference

Base URL

Authentication

Endpoints

Record Seed Acquisition

Record Planting

Record Growing Transport

Record Harvest

Record Distribution

Record Seed Saving

Record Seed Sharing

Query Endpoints

Get Plant Journey

Get Environmental Impact

Verify Block

Generate QR Code

Error Codes

Rate Limits

Webhooks

9.3 KiB

Raw Permalink Blame History