docs/architecture/01-autofarm_intelligence_stack.md

# 01 AutoFarm Architecture Overview

This document defines the current documented architecture boundary for
AutoFarm.

The active repository scope is a simulator and zone-data workflow, not a field
deployment stack.

## Decision Summary

The repository currently centers on four connected parts:

1. public-data bootstrap for provisional zone state,
2. simulator state and execution flow,
3. planning and scoring over zone-level state,
4. persistence and evaluation around simulator runs.

## Current Repo Truth

As of the current repository state:

1. `zone_state_bootstrap` is the active processed dataset used to seed
   simulator state,
2. the bootstrap is built from public soil, weather, and elevation sources,
3. the simulator provides an interactive Streamlit interface plus programmatic
   evaluation hooks,
4. snapshots and event history are persisted for interactive sessions,
5. the repository does not document field-deployment behavior or treatment
   execution.

## System Context

```mermaid
flowchart LR
  subgraph Inputs
    Boundary["Field Boundary / Scenario Setup"]
    PublicData["Public Soil / Weather / Elevation Data"]
    Operator["Operator Input"]
  end

  subgraph Core
    Bootstrap["Zone-State Bootstrap"]
    State["Simulator State"]
    Score["Scoring / Planning"]
    Execute["Step Execution"]
    Persist["Session Persistence"]
  end

  subgraph Outputs
    UI["Streamlit Simulator"]
    Reports["Evaluation / Run Artifacts"]
  end

  Boundary --> Bootstrap
  PublicData --> Bootstrap
  Bootstrap --> State
  Operator --> Score
  State --> Score
  Score --> Execute
  Execute --> State
  Execute --> Persist
  State --> UI
  Persist --> UI
  Persist --> Reports
```

## Design Rules

1. zone data should enter the simulator through explicit processed artifacts,
2. planning should operate on zone-level state instead of ad hoc UI state,
3. execution should advance in discrete steps so state transitions remain easy
   to inspect,
4. persistence should preserve enough context to resume or audit a session,
5. documentation should describe only the currently supported simulator and
   data-bootstrap surface.

## Primary Source Files

- `scripts/build_zone_state_bootstrap.py`
- `scripts/run_public_data_pipeline.py`
- `autofarm/adapters/zone_state.py`
- `autofarm/planning/scoring.py`
- `autofarm/planning/policy.py`
- `autofarm/sim/engine.py`
- `autofarm/sim/session_persistence.py`
- `apps/simulator.py`