> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agronome.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Farms and Fields

> ADAPT hierarchy — farms, fields, boundaries, and crop zones

# Farms and Fields

agronome.ai follows the [ADAPT (AgGateway)](https://adaptframework.org/) data model for representing agricultural entities. This provides a consistent structure that maps cleanly to equipment manufacturers (John Deere, CNH) and agronomic data standards.

## Hierarchy

```
Organization
  └── Farm
       └── Field
            ├── FieldBoundary (versioned geometry)
            └── CropZone (sub-field management unit)
```

### Farm

A farm is a named grouping of fields. It typically represents a physical farming operation or a geographic grouping.

* Belongs to exactly one organization
* Has a name and optional location
* Contains one or more fields

### Field

A field is a contiguous area of land managed as a single unit.

* Belongs to exactly one farm
* Has one **active boundary** at any time (boundaries are versioned — historical boundaries are preserved)
* Can contain multiple crop zones
* All data layers (drone imagery, satellite, soil samples) are linked to the field

### FieldBoundary

A versioned polygon geometry stored in PostGIS. When you update a field's boundary, the previous boundary is preserved with its effective date range. This allows historical analysis — "what did this field look like last season?"

* Stored as `GEOMETRY(POLYGON, 4326)` (WGS 84)
* Area is calculated automatically on save
* Supports import from shapefiles, GeoJSON, or manual drawing on the map

### CropZone

A sub-field management unit representing a specific crop or management practice within a field.

* Belongs to exactly one field
* Has its own boundary (must be within the parent field boundary)
* Tracks crop type (EPPO standard codes), planting date, and season
* Used for per-zone analysis (e.g., NDVI averages by crop zone)

## External IDs

When fields are imported from third-party providers (John Deere, CNH), the external identifiers are stored in an `external_ids` JSONB column. This enables two-way sync and deduplication on re-import.

```json theme={null}
{
  "john_deere": {
    "field_id": "abc-123",
    "organization_id": "jd-org-456"
  }
}
```

## Spatial operations

All boundary operations use PostGIS for server-side spatial computation:

* **Area calculation** — `ST_Area` with geography cast for accurate metric area
* **Containment** — `ST_Contains` verifies crop zones are within field boundaries
* **Intersection** — `ST_Intersects` for overlap detection
* **Centroid** — `ST_Centroid` for map centering and label placement