SmartCane/.github/copilot-instructions.md

Copilot Instructions for SmartCane Codebase

Big Picture Architecture

• Three main components:
  • r_app/: R scripts for crop analysis, package management, and reporting
  • python_app/ & python_scripts/: Python notebooks and scripts for satellite data download and preprocessing
  • laravel_app/: Laravel PHP web application for user-facing features
• Data Flow:
  • Satellite data is downloaded/preprocessed in Python, stored in python_scripts/data/
  • R scripts in r_app/ analyze, visualize, and report on this data
  • Reports and outputs are saved in output/
  • Laravel app may consume outputs for web display (integration is project-specific)

Critical Developer Workflows

• R Package Management:
  • Always run r_app/package_manager.R after pulling changes or before analysis
  • Commit renv.lock but NOT the renv/ folder
  • Use source("r_app/package_manager.R") in RStudio or Rscript r_app/package_manager.R in terminal
• Crop Analysis:
  • Main script: r_app/crop_analysis_messaging.R
  • Usage: Rscript crop_analysis_messaging.R [week1] [week2] [farm]
  • Output: Alerts, summary stats, and recommendations (see PACKAGE_MANAGEMENT.md for logic)
• SAR Analysis & Reporting:
  • Main report: r_app/experiments/interactive_sar_visualization/Interactive_SAR_Report.Rmd
  • Generate with: rmarkdown::render("Interactive_SAR_Report.Rmd", output_file = "../../../output/Interactive_SAR_Report.html")
  • Data source: python_scripts/data/aura/weekly_SAR_mosaic/
• Python Data Download:
  • Notebooks/scripts in python_app/ and python_scripts/ handle satellite data acquisition
  • Check requirements_*.txt for dependencies
• Laravel App:
  • Standard Laravel conventions (see laravel_app/README.md)
  • Use artisan for migrations, tests, etc.

Project-Specific Conventions

• Field Uniformity & Alerting:
  • Uniformity thresholds and alert logic are defined in PACKAGE_MANAGEMENT.md
  • Message categories: 🚨 URGENT, ⚠️ ALERT, ✅ POSITIVE, 💡 OPPORTUNITY
  • Spatial pattern analysis uses Moran's I (see R scripts)
• Package Management:
  • Minimum versions enforced for critical R packages (see PACKAGE_MANAGEMENT.md)
  • All package changes go through package_manager.R
• Output Files:
  • Reports and logs go in output/
  • Do NOT commit logs or cache folders

Integration Points & Dependencies

• R ↔ Python:
  • R scripts expect preprocessed data from Python scripts
  • Data location conventions: python_scripts/data/, pivot.geojson
• R ↔ Laravel:
  • Laravel may read outputs from R analysis (integration is custom)
• External:
  • Sentinel-1 SAR data, field boundaries (GeoJSON), R/Python packages

Examples

• To run a full crop analysis workflow:

  Rscript r_app/package_manager.R ; Rscript r_app/crop_analysis_messaging.R 32 31 simba
  

• To generate SAR report:

  rmarkdown::render("r_app/experiments/interactive_sar_visualization/Interactive_SAR_Report.Rmd", output_file = "output/Interactive_SAR_Report.html")
  

Key Files & Directories

• r_app/package_manager.R, PACKAGE_MANAGEMENT.md: Package logic & workflow
• r_app/crop_analysis_messaging.R: Crop analysis logic
• r_app/experiments/interactive_sar_visualization/: SAR analysis & reporting
• python_scripts/, python_app/: Data download/preprocessing
• output/: All generated reports
• laravel_app/: Web application

Environment Notes

• On Windows, R can be found at: C:\Program Files\R\R-4.4.3\bin\x64\R.exe

---

If any section is unclear or missing, please provide feedback for further refinement.