# abdelghanibelgaid/agrs architecture

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

- Interactive diagram: https://gitdiagram.com/abdelghanibelgaid/agrs
- Repository: https://github.com/abdelghanibelgaid/agrs

## Overview

##### Project Type and Purpose
- This is an open-source, domain-specific Python library (AGRS) for agricultural remote sensing.
- It provides opinionated pipelines to search Sentinel-2 imagery, compute agronomic indices, select snapshots, aggregate to field-level features, and return a tidy DataFrame.
- There is no separate “frontend” or “backend” service; rather, it’s a modular library that orchestrates data retrieval and processing via the Microsoft Planetary Computer STAC API.

##### High-Level Components
a. Entry Point
- agrs/client.py
- Factory function `s2agc()` returns a client instance.
- Public API method: `client.get_features(...)`.
b. Configuration
- agrs/config.py
- Holds default parameters (e.g., indices list, snapshot strategies).
c. Data Source Integration
- agrs/sources/planetary_computer_source.py
- STAC queries, scene retrieval, cloud masks.
- Wraps HTTP calls to Planetary Computer STAC API.
d. Index Computation
- agrs/indices.py
- Implements band-math formulas for NDVI, EVI, SAVI, etc.
e. Snapshot Selection
- agrs/selection.py
- Implements strategies: fractional, fixed_date, top_n_cloudfree.
f. Aggregation
- agrs/aggregation.py
- Aggregates pixel-level indices to field-level statistics (mean, median, etc.) per growth stage.
g. Utilities
- agrs/utils.py
- GeoDataFrame clipping, date utilities, error handling, logging.
h. Packaging & Metadata
- setup.py, pyproject.toml, requirements.txt

##### External Dependencies and Services
- Planetary Computer STAC API (external service).
- GeoPandas & Shapely (field geometry).
- Pandas (DataFrame).
- HTTP client library (requests or similar, abstracted by source module).

##### Relationships and Data Flow
1. User code calls `s2agc().get_features(fields, ...)`.
2. Client reads config and passes parameters to the Source module.
3. Source module queries STAC API → downloads imagery assets.
4. Retrieved imagery → passed to Index module → computes spectral indices per scene.
5. Computed indices → passed to Selection module → selects snapshots per strategy.
6. Selected snapshots → passed to Aggregation module → computes field-level statistics by growth stage.
7. Final tidy DataFrame returned to user.

##### Architectural Patterns & Design Principles
- Modular layering: each concern (I/O, computation, selection, aggregation) in its own module.
- Chain of responsibility / pipeline pattern: data flows through sequential processing stages.
- Factory pattern in client creation for pluggable sources or future strategies.
- Opinionated defaults in config for reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "AGRS Library"
        direction TB
        CLIENT["Client\nagrs/client.py\nFactory: s2agc(), get_features()"]:::module
        CONFIG["Config\nagrs/config.py\ndefault parameters"]:::module
        SOURCE["Source\nagrs/sources/planetary_computer_source.py\nSTAC queries, cloud masks"]:::module
        INDICES["Indices\nagrs/indices.py\ncompute NDVI, EVI, SAVI"]:::module
        SELECTION["Selection\nagrs/selection.py\nsnapshot strategies"]:::module
        AGG["Aggregation\nagrs/aggregation.py\nfield-level statistics"]:::module
        UTILS["Utils\nagrs/utils.py\nGeoDataFrame clipping, date utils, logging"]:::module
        INIT["Library Init\nagrs/__init__.py"]:::module
    end

    subgraph "Packaging & Metadata"
        direction TB
        SETUP["setup.py"]:::module
        PYPROJ["pyproject.toml"]:::module
        REQS["requirements.txt"]:::module
    end

    USER["User Code\nexamples/01_basic_sentinel2_usage.py"]:::external
    STAC["Planetary Computer STAC API"]:::external
    END["Features DataFrame\n(pandas.DataFrame)"]:::data

    USER -->|"fields GeoDataFrame"| CLIENT
    CLIENT -->|"reads defaults"| CONFIG
    CLIENT -->|"passes params"| SOURCE
    SOURCE -->|"STAC queries & imagery"| STAC
    STAC -->|"imagery assets"| SOURCE
    SOURCE -->|"raw imagery"| INDICES
    INDICES -->|"index arrays"| SELECTION
    SELECTION -->|"snapshot list"| AGG
    AGG -->|"features DataFrame"| END

    UTILS -.-> CLIENT
    UTILS -.-> SOURCE
    UTILS -.-> INDICES
    UTILS -.-> SELECTION
    UTILS -.-> AGG

    classDef module fill:#D6E9FF,stroke:#4A6FA5,color:#000;
    classDef external fill:#DFF0D8,stroke:#3C763D,color:#000;
    classDef data fill:#FDEBD0,stroke:#BA4A00,color:#000;

    click CLIENT "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/client.py"
    click CONFIG "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/config.py"
    click SOURCE "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/sources/planetary_computer_source.py"
    click INDICES "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/indices.py"
    click SELECTION "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/selection.py"
    click AGG "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/aggregation.py"
    click UTILS "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/utils.py"
    click INIT "https://github.com/abdelghanibelgaid/agrs/blob/main/agrs/__init__.py"
    click SETUP "https://github.com/abdelghanibelgaid/agrs/blob/main/setup.py"
    click PYPROJ "https://github.com/abdelghanibelgaid/agrs/blob/main/pyproject.toml"
    click REQS "https://github.com/abdelghanibelgaid/agrs/blob/main/requirements.txt"
    click USER "https://github.com/abdelghanibelgaid/agrs/blob/main/examples/01_basic_sentinel2_usage.py"
```
