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

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