# Consumer Guide

How to use LocalGreenChain to find, purchase, and track local produce.

## Getting Started

### Create Your Profile

Register as a consumer to receive personalized recommendations:

```typescript
// Consumer profile
{
  consumerId: "consumer-uuid",
  location: {
    latitude: 40.7128,
    longitude: -74.0060,
    maxDeliveryRadiusKm: 25,
    city: "Brooklyn"
  },
  householdSize: 4,
  weeklyBudget: 75
}
```

## Setting Your Preferences

### Food Preferences

Tell us what you like:

```typescript
POST /api/demand/preferences

{
  consumerId: "your-id",

  // Dietary needs
  dietaryType: ["vegetarian"],
  allergies: ["peanuts"],
  dislikes: ["cilantro"],

  // What you want
  preferredCategories: [
    "leafy_greens",
    "herbs",
    "nightshades"
  ],

  preferredItems: [
    {
      produceType: "tomato",
      priority: "must_have",
      weeklyQuantity: 2,  // kg
      seasonalOnly: true
    },
    {
      produceType: "lettuce",
      priority: "preferred",
      weeklyQuantity: 1
    },
    {
      produceType: "basil",
      priority: "nice_to_have"
    }
  ],

  // Quality preferences
  certificationPreferences: ["organic", "local"],
  freshnessImportance: 5,  // 1-5 scale
  priceImportance: 3,
  sustainabilityImportance: 5,

  // Delivery
  deliveryPreferences: {
    method: ["home_delivery", "farmers_market"],
    frequency: "weekly",
    preferredDays: ["saturday"]
  }
}
```

### Priority Levels Explained

| Priority | Meaning | System Behavior |
|----------|---------|-----------------|
| `must_have` | Essential items | Prioritizes matching these first |
| `preferred` | Strong preference | Tries to include when possible |
| `nice_to_have` | Would enjoy | Adds if supply available |
| `occasional` | Sometimes interested | Suggests opportunistically |

## Finding Local Produce

### Browse Available Produce

```typescript
GET /api/plants/nearby?lat=40.7128&lon=-74.0060&radius=25
```

### View Grower Profiles

Each grower shows:
- Location and distance from you
- Available produce
- Certifications (organic, etc.)
- Delivery methods
- Customer ratings

### Check Seasonal Availability

```
SPRING (Mar-May)
├── Lettuce ✓ Available locally
├── Spinach ✓ Available locally
├── Peas ✓ Limited supply
└── Tomatoes ✗ Not in season

SUMMER (Jun-Aug)
├── Tomatoes ✓ Peak availability
├── Peppers ✓ Available locally
├── Basil ✓ Abundant
└── Cucumbers ✓ Available locally
```

## Understanding Plant History

### Scanning QR Codes

Every item from LocalGreenChain has a QR code. Scan to see:

1. **Complete Journey** - From seed to your table
2. **Growing Conditions** - Environment during growth
3. **Transport History** - Every movement tracked
4. **Carbon Footprint** - Environmental impact
5. **Grower Info** - Who grew it and where

### What You'll See

```json
{
  "plantId": "lgc_abc123",
  "journey": {
    "seedOrigin": "Heritage Seed Bank",
    "grower": "Green Valley Farm",
    "location": "Brooklyn, NY",
    "distance": "12 miles from you",
    "harvestDate": "2024-08-01",
    "daysFromHarvest": 1
  },
  "environmental": {
    "growingMethod": "greenhouse",
    "certifications": ["organic"],
    "carbonFootprint": "0.15 kg CO2/kg",
    "waterUsage": "10% of conventional"
  },
  "lineage": {
    "generation": 3,
    "parentPlantIds": ["plant-parent-001"],
    "variety": "Cherokee Purple Heirloom"
  }
}
```

## Ordering and Delivery

### Place an Order

Match with available supply:

```typescript
POST /api/demand/match

{
  consumerId: "your-id",
  supplyCommitmentId: "supply-123",
  produceType: "tomato",
  matchedQuantityKg: 2,
  deliveryDate: "2024-08-03",
  deliveryMethod: "home_delivery"
}
```

### Delivery Options

| Method | Description | Typical Cost |
|--------|-------------|--------------|
| `home_delivery` | Direct to your door | $$ |
| `pickup_point` | Central pickup location | $ |
| `farmers_market` | Weekly market booth | Free |
| `csa_distribution` | CSA share pickup | Subscription |

### Track Your Delivery

```typescript
GET /api/transport/journey/order-123
```

Real-time updates on:
- Current location
- Estimated arrival
- Temperature during transport
- Handler information

## Providing Feedback

### Rate Your Experience

After receiving produce:

```typescript
POST /api/feedback

{
  orderId: "order-123",
  rating: 5,
  qualityScore: 5,
  freshnessScore: 5,
  feedback: "Absolutely fresh, arrived within hours of harvest!"
}
```

### Report Issues

If something isn't right:

```typescript
POST /api/feedback/issue

{
  orderId: "order-123",
  issueType: "quality",
  description: "Lettuce was wilted on arrival",
  photos: ["url-to-photo"]
}
```

## Environmental Impact

### Your Personal Impact

Track your contribution to sustainable agriculture:

```typescript
GET /api/consumer/impact/your-id
```

Response:

```json
{
  "totalPurchasesKg": 45,
  "carbonSavedKg": 112,
  "milesSaved": 67500,
  "waterSavedLiters": 4500,
  "localGrowersSupported": 8,
  "comparisonToConventional": {
    "carbonReduction": "89%",
    "waterReduction": "90%",
    "foodMilesReduction": "97%"
  }
}
```

### Understanding the Numbers

| Your Purchase | Conventional | LocalGreenChain | Savings |
|---------------|--------------|-----------------|---------|
| 1 kg tomatoes | 2.8 kg CO2 | 0.3 kg CO2 | 2.5 kg |
| Food miles | 1,500 miles | 12 miles | 1,488 mi |
| Water use | 50 liters | 5 liters | 45 L |

## Seasonal Planning

### Subscribe to Updates

Get notified when your favorites become available:

```typescript
POST /api/consumer/alerts

{
  produceType: "strawberry",
  alertType: "in_season",
  notification: "email"
}
```

### Seasonal Calendar

Plan your eating around what's fresh:

```
JAN: Microgreens, Sprouts, Winter Greens
FEB: Microgreens, Early Sprouts
MAR: Lettuce, Spinach, Radishes
APR: Spring Greens, Peas, Herbs
MAY: Strawberries, Asparagus, Greens
JUN: Early Tomatoes, Cucumbers, Basil
JUL: Peak Tomatoes, Peppers, Corn
AUG: Melons, Squash, Late Tomatoes
SEP: Apples, Winter Squash, Kale
OCT: Root Vegetables, Late Greens
NOV: Storage Crops, Greens
DEC: Winter Storage, Microgreens
```

## Best Practices

### For Best Quality

1. **Order In Season** - Peak flavor and nutrition
2. **Accept Some Variation** - Farm-fresh isn't uniform
3. **Plan Ahead** - Pre-order for best selection
4. **Store Properly** - Follow storage guidelines

### For Maximum Impact

1. **Buy Local First** - Lower carbon footprint
2. **Support Small Growers** - Build community
3. **Accept Imperfect** - Reduce food waste
4. **Provide Feedback** - Help improve the system

### For Community

1. **Share with Neighbors** - Group orders reduce delivery
2. **Attend Markets** - Meet your growers
3. **Spread the Word** - Grow the network
4. **Save Seeds** - Close the loop

## Frequently Asked Questions

### How fresh is the produce?

Most items are harvested within 24-48 hours of delivery. The blockchain record shows exact harvest time.

### Is everything organic?

Not all growers are certified organic, but all practices are transparent. Check certifications in the plant profile.

### What if my order is wrong?

Contact support immediately. All issues are tracked and resolved. Our blockchain ensures accountability.

### Can I request specific varieties?

Yes! Set preferences for specific varieties. Growers see demand signals and may grow what you request.

## Next Steps

- [Grower Guide](./grower-guide.md) - Understand how your food is grown
- [Transport Guide](./transport-guide.md) - Learn about the journey
- [Quick Start](./quick-start.md) - Get started immediately