# isjustabhi/farmshield-ai architecture

> Architecture diagram of the GitHub repository isjustabhi/farmshield-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isjustabhi/farmshield-ai
- Repository: https://github.com/isjustabhi/farmshield-ai

## Overview

FarmShield AI coordinates tractor jobs in a deterministic farm simulator, then exposes fleet state and operational insights through a live dashboard. The core workflow is: a user monitors or controls the fleet; the API invokes scheduling, navigation, and safety checks before assignments are committed; simulation ticks track travel and work; disruption recovery preserves progress and replans through those gates. The README documents benchmark, chaos, memory, and metrics capabilities. Some subsystem links reflect README-level documentation because their implementation excerpts were not shown.

Main entry points: [`frontend/src/App.tsx`](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/App.tsx) (Dashboard shell), [`backend/app/orchestration.py`](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/orchestration.py) (Agent orchestration), [`backend/app/main.py`](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/simulation.py`](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/simulation.py) (Authoritative simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Fleet dashboard"]
  node_app["Dashboard shell<br/>[App.tsx]"]
  node_fleetdata["Fleet data hook<br/>[useFleetData.ts]"]
  node_command["Command center"]
  node_fleetview["Fleet monitor"]
  node_missions["Mission queue"]
  node_chaosview["Chaos lab<br/>[ChaosLabPage.tsx]"]
  node_agentsview["Agent network"]
  node_memoryview["Incident memory"]
  node_benchmarkview["Benchmark lab"]
  node_intelligence["Intelligence view"]
end

subgraph group_api["API boundary"]
  node_api_client["HTTP API client<br/>[api.ts]"]
  node_schemas["Shared API types<br/>[api.ts]"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_simulation["Authoritative simulator<br/>[simulation.py]"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_coordination["Planning and recovery"]
  node_fleetagent["Fleet scheduler<br/>[scheduler.py]"]
  node_baseline["FCFS baseline<br/>[baseline.py]"]
  node_orchestration["Agent orchestration<br/>[orchestration.py]"]
  node_navigation["A-star navigation<br/>[navigation.py]"]
  node_safety["Safety validation<br/>[safety.py]"]
  node_recovery["Recovery agent<br/>[recovery.py]"]
end

subgraph group_insights["Operational insights"]
  node_chaos["Seeded disruptions<br/>[chaos.py]"]
  node_benchmark["Benchmark harness<br/>[benchmark.py]"]
  node_metrics["Productivity analytics<br/>[metrics.py]"]
  node_memory[("Operational memory<br/>[memory.py]")]
end

node_operator(("Fleet operator"))

node_operator -->|"uses"| node_app
node_app -->|"loads data"| node_fleetdata
node_app -->|"renders"| node_command
node_app -->|"renders"| node_fleetview
node_app -->|"renders"| node_missions
node_app -->|"renders"| node_chaosview
node_app -->|"renders"| node_agentsview
node_app -->|"renders"| node_memoryview
node_app -->|"renders"| node_benchmarkview
node_app -->|"renders"| node_intelligence
node_fleetdata -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"controls state"| node_simulation
node_fastapi -->|"dispatches events"| node_orchestration
node_fastapi -->|"runs comparisons"| node_benchmark
node_fastapi -->|"exposes disruptions"| node_chaos
node_fastapi -->|"serves analytics"| node_metrics
node_orchestration -->|"requests schedule"| node_fleetagent
node_orchestration -->|"requests routes"| node_navigation
node_orchestration -->|"validates proposals"| node_safety
node_orchestration -->|"commits assignments"| node_simulation
node_orchestration -->|"requests replans"| node_recovery
node_baseline -->|"requests routes"| node_navigation
node_baseline -->|"validates commits"| node_safety
node_simulation -->|"records activity"| node_metrics
node_simulation -->|"records events"| node_memory
node_chaos -->|"injects events"| node_simulation
node_benchmark -->|"compares planner"| node_baseline
node_benchmark -->|"compares planner"| node_fleetagent
node_orchestration -->|"persists traces"| node_memory
node_metrics -->|"reads history"| node_memory
node_fleetview -->|"uses data types"| node_schemas
node_command -->|"uses data types"| node_schemas
node_benchmarkview -->|"requests results"| node_api_client
node_intelligence -->|"requests analytics"| node_api_client

click node_app "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/App.tsx"
click node_fleetdata "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/hooks/useFleetData.ts"
click node_command "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/CommandCenterPage.tsx"
click node_fleetview "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/FleetMonitorPage.tsx"
click node_missions "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/MissionQueuePage.tsx"
click node_chaosview "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/ChaosLabPage.tsx"
click node_agentsview "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/AgentNetworkPage.tsx"
click node_memoryview "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/IncidentMemoryPage.tsx"
click node_benchmarkview "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/BenchmarkLabPage.tsx"
click node_intelligence "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/IntelligencePage.tsx"
click node_api_client "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/services/api.ts"
click node_schemas "https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/types/api.ts"
click node_fastapi "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/main.py"
click node_simulation "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/simulation.py"
click node_models "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/models.py"
click node_fleetagent "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/scheduler.py"
click node_baseline "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/baseline.py"
click node_orchestration "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/orchestration.py"
click node_navigation "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/navigation.py"
click node_safety "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/safety.py"
click node_recovery "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/recovery.py"
click node_chaos "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/chaos.py"
click node_benchmark "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/benchmark.py"
click node_metrics "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/metrics.py"
click node_memory "https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/memory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_fleetdata,node_command,node_fleetview,node_missions,node_chaosview,node_agentsview,node_memoryview,node_benchmarkview,node_intelligence toneBlue
class node_api_client,node_schemas,node_fastapi toneAmber
class node_simulation,node_models toneMint
class node_fleetagent,node_baseline,node_orchestration,node_navigation,node_safety,node_recovery toneRose
class node_chaos,node_benchmark,node_metrics,node_memory,node_operator toneIndigo
```

## Components

### Fleet dashboard

- [Dashboard shell](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Fleet data hook](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/hooks/useFleetData.ts): `frontend/src/hooks/useFleetData.ts`
- [Command center](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/CommandCenterPage.tsx): `frontend/src/pages/CommandCenterPage.tsx`
- [Fleet monitor](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/FleetMonitorPage.tsx): `frontend/src/pages/FleetMonitorPage.tsx`
- [Mission queue](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/MissionQueuePage.tsx): `frontend/src/pages/MissionQueuePage.tsx`
- [Chaos lab](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/ChaosLabPage.tsx): `frontend/src/pages/ChaosLabPage.tsx`
- [Agent network](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/AgentNetworkPage.tsx): `frontend/src/pages/AgentNetworkPage.tsx`
- [Incident memory](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/IncidentMemoryPage.tsx): `frontend/src/pages/IncidentMemoryPage.tsx`
- [Benchmark lab](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/BenchmarkLabPage.tsx): `frontend/src/pages/BenchmarkLabPage.tsx`
- [Intelligence view](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/pages/IntelligencePage.tsx): `frontend/src/pages/IntelligencePage.tsx`

### API boundary

- [HTTP API client](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Shared API types](https://github.com/isjustabhi/farmshield-ai/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`
- [FastAPI routes](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Simulation runtime

- [Authoritative simulator](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/simulation.py): `backend/app/simulation.py`
- [Domain models](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/models.py): `backend/app/models.py`

### Planning and recovery

- [Fleet scheduler](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/scheduler.py): `backend/app/scheduler.py`
- [FCFS baseline](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/baseline.py): `backend/app/baseline.py`
- [Agent orchestration](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/orchestration.py): `backend/app/orchestration.py`
- [A-star navigation](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/navigation.py): `backend/app/navigation.py`
- [Safety validation](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/safety.py): `backend/app/safety.py`
- [Recovery agent](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/recovery.py): `backend/app/recovery.py`

### Operational insights

- [Seeded disruptions](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/chaos.py): `backend/app/chaos.py`
- [Benchmark harness](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/benchmark.py): `backend/app/benchmark.py`
- [Productivity analytics](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/metrics.py): `backend/app/metrics.py`
- [Operational memory](https://github.com/isjustabhi/farmshield-ai/blob/main/backend/app/memory.py): `backend/app/memory.py`

### Other components

- **Fleet operator**

## Connections

- Fleet operator → Dashboard shell: uses (evidence: `README.md`)
- Dashboard shell → Fleet data hook: loads data (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Command center: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Fleet monitor: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Mission queue: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Chaos lab: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Agent network: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Incident memory: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Benchmark lab: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Intelligence view: renders (evidence: `frontend/src/App.tsx`)
- Fleet data hook → HTTP API client: calls (evidence: `frontend/src/hooks/useFleetData.ts`)
- HTTP API client → FastAPI routes: HTTP requests (evidence: `README.md`)
- FastAPI routes → Authoritative simulator: controls state (evidence: `backend/app/main.py`)
- FastAPI routes → Agent orchestration: dispatches events (evidence: `README.md`)
- FastAPI routes → Benchmark harness: runs comparisons (evidence: `backend/app/main.py`)
- FastAPI routes → Seeded disruptions: exposes disruptions (evidence: `backend/app/main.py`)
- FastAPI routes → Productivity analytics: serves analytics (evidence: `backend/app/main.py`)
- Agent orchestration → Fleet scheduler: requests schedule (evidence: `backend/app/orchestration.py`)
- Agent orchestration → A-star navigation: requests routes (evidence: `backend/app/orchestration.py`)
- Agent orchestration → Safety validation: validates proposals (evidence: `backend/app/orchestration.py`)
- Agent orchestration → Authoritative simulator: commits assignments (evidence: `README.md`)
- Agent orchestration → Recovery agent: requests replans (evidence: `backend/app/orchestration.py`)
- FCFS baseline → A-star navigation: requests routes (evidence: `backend/app/baseline.py`)
- FCFS baseline → Safety validation: validates commits (evidence: `backend/app/baseline.py`)
- Authoritative simulator → Productivity analytics: records activity (evidence: `backend/app/simulation.py`)
- Authoritative simulator → Operational memory: records events (evidence: `README.md`)
- Seeded disruptions → Authoritative simulator: injects events (evidence: `backend/app/chaos.py`)
- Benchmark harness → FCFS baseline: compares planner (evidence: `README.md`)
- Benchmark harness → Fleet scheduler: compares planner (evidence: `README.md`)
- Agent orchestration → Operational memory: persists traces (evidence: `README.md`)
- Productivity analytics → Operational memory: reads history (evidence: `backend/app/metrics.py`)
- Fleet monitor → Shared API types: uses data types (evidence: `frontend/src/pages/FleetMonitorPage.tsx`)
- Command center → Shared API types: uses data types (evidence: `frontend/src/pages/CommandCenterPage.tsx`)
- Benchmark lab → HTTP API client: requests results (evidence: `frontend/src/pages/BenchmarkLabPage.tsx`)
- Intelligence view → HTTP API client: requests analytics (evidence: `frontend/src/pages/IntelligencePage.tsx`)
