localgreenchain/docs/concepts/demand-forecasting.md

Demand Forecasting & Seasonal Planning

LocalGreenChain's demand forecasting system enables truly demand-driven agriculture by connecting consumer preferences with grower capabilities, optimizing for seasonal availability and minimal environmental impact.

Core Philosophy

Traditional Agriculture Problem

Grower decides → Plants → Harvests → Finds buyers → Surplus/shortage
     ↓              ↓         ↓           ↓              ↓
   Guesses      Fixed plan  Hope sells  Waste if not  Lost income

LocalGreenChain Solution

Consumer signals → Aggregated demand → Grower recommendation → Matched harvest
       ↓                  ↓                    ↓                    ↓
   Preferences     Regional needs       Optimal planting      Pre-sold produce

Demand Signal Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    DEMAND SIGNAL GENERATION                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  CONSUMER PREFERENCES                                               │
│  ┌─────────────────┐                                               │
│  │ Consumer A      │──┐                                            │
│  │ - Tomatoes: 2kg │  │                                            │
│  │ - Lettuce: 1kg  │  │                                            │
│  │ - Organic only  │  │                                            │
│  └─────────────────┘  │                                            │
│  ┌─────────────────┐  │      ┌─────────────────────┐              │
│  │ Consumer B      │──┼─────→│  DEMAND AGGREGATOR  │              │
│  │ - Tomatoes: 1kg │  │      │                     │              │
│  │ - Basil: 200g   │  │      │  Region: Downtown   │              │
│  │ - Local pref    │  │      │  Radius: 25km       │              │
│  └─────────────────┘  │      │  Season: Summer     │              │
│  ┌─────────────────┐  │      │                     │              │
│  │ Consumer C...   │──┘      │  Total Consumers:   │              │
│  │                 │         │  150                │              │
│  └─────────────────┘         └──────────┬──────────┘              │
│                                         │                          │
│                                         ▼                          │
│                              ┌─────────────────────┐              │
│                              │   DEMAND SIGNAL     │              │
│                              │                     │              │
│                              │ Tomatoes: 180kg/wk  │              │
│                              │ Lettuce: 95kg/wk    │              │
│                              │ Basil: 15kg/wk      │              │
│                              │                     │              │
│                              │ Gap: 120kg tomatoes │              │
│                              │ Status: SHORTAGE    │              │
│                              └─────────────────────┘              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Consumer Preferences

Preference Structure

interface ConsumerPreference {
  // Who
  consumerId: string;
  location: { latitude, longitude, maxDeliveryRadiusKm };

  // What they want
  preferredCategories: ['leafy_greens', 'herbs', 'nightshades'];
  preferredItems: [
    { produceType: 'tomato', priority: 'must_have', weeklyQuantity: 2 },
    { produceType: 'lettuce', priority: 'preferred', weeklyQuantity: 1 },
    { produceType: 'basil', priority: 'nice_to_have' }
  ];

  // How they want it
  certificationPreferences: ['organic', 'local'];
  deliveryPreferences: {
    method: ['home_delivery', 'farmers_market'],
    frequency: 'weekly'
  };

  // Constraints
  householdSize: 4;
  weeklyBudget: 75;
}

Priority Levels

Priority	Weight	Meaning
must_have	10	Essential - will seek elsewhere if not available
preferred	7	Strong preference - important for satisfaction
nice_to_have	4	Would enjoy - not essential
occasional	2	Sometimes interested - opportunistic

Demand Signals

Regional Aggregation

Demand signals aggregate preferences within a geographic region:

interface DemandSignal {
  region: { centerLat, centerLon, radiusKm, name };
  seasonalPeriod: 'summer';

  demandItems: [
    {
      produceType: 'tomato',
      weeklyDemandKg: 180,
      consumerCount: 95,
      aggregatePriority: 8.5,
      urgency: 'this_week',
      inSeason: true,
      matchedSupply: 60,
      gapKg: 120  // Opportunity for growers!
    }
  ];

  supplyStatus: 'shortage';  // surplus | balanced | shortage | critical
}

Supply Matching

The system continuously matches demand with available supply:

Demand: 180 kg/week tomatoes

Current Supply:
  - Grower A: 30 kg committed
  - Grower B: 20 kg committed
  - Vertical Farm X: 10 kg committed
  Total: 60 kg

Gap: 120 kg/week

→ Generate planting recommendations for growers
→ Vertical farms can respond within 6-8 weeks
→ Traditional growers plan for next season

Planting Recommendations

Recommendation Engine

// Generate recommendations for a grower
const recommendations = forecaster.generatePlantingRecommendations(
  growerId,
  growerLat,
  growerLon,
  deliveryRadiusKm: 50,
  availableSpaceSqm: 1000,
  season: 'summer'
);

// Returns prioritized recommendations
[
  {
    produceType: 'tomato',
    recommendedQuantity: 200, // sqm
    expectedYieldKg: 1600,
    projectedDemandKg: 480, // monthly gap
    projectedPricePerKg: 4.50,
    projectedRevenue: 7200,
    riskFactors: [...],
    explanation: "Based on 3 demand signals showing 120kg weekly gap..."
  },
  {
    produceType: 'lettuce',
    recommendedQuantity: 100,
    ...
  }
]

Risk Assessment

Each recommendation includes risk factors:

Risk Type	Description	Mitigation
weather	Outdoor crop vulnerable to conditions	Consider greenhouse
oversupply	Other growers may fill gap	Start smaller, scale up
market	Demand may shift	Diversify crops
pest	Known pest pressure in region	Preventive measures

Seasonal Planning

Seasonal Crop Calendar

SPRING (Mar-May)
├── Lettuce ★★★★★
├── Spinach ★★★★★
├── Peas ★★★★☆
├── Radishes ★★★★☆
└── Carrots ★★★☆☆

SUMMER (Jun-Aug)
├── Tomatoes ★★★★★
├── Peppers ★★★★★
├── Cucumbers ★★★★☆
├── Basil ★★★★★
└── Beans ★★★★☆

FALL (Sep-Nov)
├── Kale ★★★★★
├── Broccoli ★★★★☆
├── Brussels Sprouts ★★★★☆
├── Squash ★★★★☆
└── Lettuce ★★★★★

WINTER (Dec-Feb)
├── Microgreens ★★★★★ (indoor)
├── Sprouts ★★★★★ (indoor)
├── Kale ★★★★☆
└── Spinach ★★★☆☆

★ = Demand strength in season

Year-Round Planning with Vertical Farms

Vertical farms can produce year-round, filling seasonal gaps:

Traditional Supply:  ████████████░░░░░░░░░░████████████
Vertical Farm:       ████████████████████████████████████
Combined:            ████████████████████████████████████

Legend: █ = Supply available, ░ = Gap

Forecasting Models

Simple Moving Average

// Basic forecast from historical data
const forecast = history.reduce((a, b) => a + b, 0) / history.length;

Seasonal Adjustment

// Apply seasonal multiplier
const seasonalFactor = isInSeason(produceType, currentSeason) ? 1.2 : 0.6;
const adjustedForecast = baseForecast * seasonalFactor;

Trend Analysis

// Detect growing/declining interest
const trend = (latestDemand - earliestDemand) / dataPoints;
const futureDemand = currentDemand + (trend * weeksAhead);

Integration Points

With Transport System

// Transport events update demand fulfillment
transportChain.recordEvent({
  eventType: 'distribution',
  batchIds: ['harvest-123'],
  destinationType: 'consumer',
  // Updates matched supply in demand signals
});

With Vertical Farms

// Vertical farms can respond quickly to demand signals
const gaps = demandSignal.demandItems.filter(i => i.gapKg > 0 && i.urgency === 'this_week');

for (const gap of gaps) {
  if (canGrowInVerticalFarm(gap.produceType)) {
    // Start batch immediately
    verticalFarmController.startCropBatch(...);
  }
}

With Blockchain

// All demand signals and commitments recorded on chain
plantChain.recordDemandSignal(signal);
plantChain.recordSupplyCommitment(commitment);
plantChain.recordMarketMatch(match);

Best Practices

For Consumers

1. Set Preferences Early: The more lead time, the better matching
2. Be Flexible: Mark some items as "nice to have"
3. Accept Seasonal Variety: In-season produce is better and cheaper
4. Provide Feedback: Help improve recommendations

For Growers

1. Register Capacity: Let the system know what you can grow
2. Follow Recommendations: Data-driven planting reduces risk
3. Commit Early: Pre-committed supply gets priority matching
4. Diversify: Grow multiple crops to balance risk

For the System

1. Aggregate Regionally: Local matching reduces transport
2. Prioritize Seasonal: In-season crops have better yields
3. Balance Supply: Prevent oversupply situations
4. Learn Continuously: Improve forecasts from actual outcomes

Environmental Impact

Demand-Driven Benefits

Metric	Traditional	Demand-Driven	Savings
Food Waste	30-40%	5-10%	75% reduction
Transport Miles	1,500 avg	< 50 local	97% reduction
Unsold Produce	20%	< 5%	75% reduction
Energy (storage)	High	Minimal	80% reduction

Carbon Calculation

Traditional Tomato (California to NYC):
  Growing: 0.5 kg CO2/kg
  Transport: 2.0 kg CO2/kg
  Storage: 0.3 kg CO2/kg
  Total: 2.8 kg CO2/kg

LocalGreenChain Tomato (local vertical farm):
  Growing: 0.3 kg CO2/kg
  Transport: 0.02 kg CO2/kg
  Storage: 0.0 kg CO2/kg
  Total: 0.32 kg CO2/kg

Savings: 89% carbon reduction