soil-test-tracker

# soil-test-tracker

Record soil test lab results, evaluate nutrient status against optimal ranges, and track amendment applications to monitor soil health improvement over time.

## When to Use

- Entering results from a soil lab report (pH, N, P, K, Ca, Mg, S, OM, CEC)
- Checking which nutrients are deficient or low for a specific field
- Viewing how a field's pH or organic matter has changed across multiple tests
- Recording a lime, fertilizer, or compost application
- Comparing nutrient status across all active fields
- Generating before/after reports for fields that have received amendments

## Key Concepts

### Nutrient Status

Each nutrient value is evaluated against configurable optimal ranges:

| Status | Meaning |
|---|---|
| Optimal | Value is within the low-to-high optimal range |
| Low | Below the low threshold but above 50% of low |
| High | Above the high threshold |
| Deficient | Below 50% of the low threshold - urgent action needed |

Default ranges can be customized per farm in Settings > Optimal Ranges.

### Default Optimal Ranges

| Nutrient | Low | High | Unit |
|---|---|---|---|
| pH | 6.0 | 7.0 | - |
| Nitrogen | 20 | 50 | ppm |
| Phosphorus | 20 | 50 | ppm |
| Potassium | 120 | 200 | ppm |
| Calcium | 1000 | 2000 | ppm |
| Magnesium | 100 | 200 | ppm |
| Sulfur | 10 | 30 | ppm |
| Organic Matter | 3.0 | 6.0 | % |

### Fields

Each field has a name, area in acres, soil type, and crop history notes. All soil tests and amendments are linked to a field.

### Amendments

When you apply lime, fertilizer, compost, or other products to correct nutrient deficiencies, record them as amendments. Link each amendment to the soil test that prompted it. The Improvement Report compares before/after values across tests to quantify the effect of amendments.

## API Quick Reference

```bash
# Add a soil test
curl -X POST http://localhost:3004/api/tests \
  -H "Content-Type: application/json" \
  -d '{
    "field_id": "...",
    "test_date": "2025-04-18",
    "lab_name": "AgLab Solutions",
    "ph": 5.9,
    "nitrogen_ppm": 19,
    "phosphorus_ppm": 22,
    "potassium_ppm": 105,
    "organic_matter_pct": 1.6,
    "cec": 12.4
  }'

# Get test with nutrient status evaluation
curl http://localhost:3004/api/tests/{id}

# List tests for a field
curl "http://localhost:3004/api/tests?field_id={id}"

# Get nutrient trends for a field
curl "http://localhost:3004/api/analytics/trends?field_id={id}"

# Get field summary (latest test status for all fields)
curl http://localhost:3004/api/analytics/field-summary

# Record an amendment
curl -X POST http://localhost:3004/api/amendments \
  -H "Content-Type: application/json" \
  -d '{
    "field_id": "...",
    "test_id": "...",
    "applied_date": "2025-04-20",
    "product_name": "Agricultural Lime",
    "rate_per_acre": 2.0,
    "unit": "ton",
    "area_acres": 4.2,
    "cost_per_unit": 30.00
  }'

# Get improvement report (before/after amendment comparison)
curl "http://localhost:3004/api/analytics/improvement?field_id={id}"
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | HTTP port | 3004 |
| DATA_DIR | SQLite directory | ./data |
| AUTH_PASSWORD | Optional login password | (empty) |
| NODE_ENV | development or production | development |
| SESSION_SECRET | Required in production | (required) |

## Troubleshooting

### Status shows "Optimal" but value seems wrong

Check the optimal ranges: `GET /api/optimal-ranges`. Ranges may have been customized. The default ranges are for general vegetable production - you may need to adjust for your specific crops.

### Field does not appear in field summary

The field summary only includes fields with at least one soil test. Add a test for the field first.

### Trends chart shows only one data point

Trend lines require at least two tests for the same field. Add a second test with a different date.