# amandeva/amini-geofm-decoding-the-field-challenge architecture

> Architecture diagram of the GitHub repository amandeva/amini-geofm-decoding-the-field-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amandeva/amini-geofm-decoding-the-field-challenge
- Repository: https://github.com/amandeva/amini-geofm-decoding-the-field-challenge

## Overview

##### Observations from the file tree
- The repository contains only:
- `Complete-project-doc.pdf`
- `README.md` with a title and two embedded images (hosted on Google Drive)

##### Likely project type and purpose
- This is **not a conventional codebase** (no `src/`, `requirements.txt`, `package.json`, etc.).
- It’s most likely a **research / ML project write-up** (or competition submission report) documenting:
- a **Geo-spatial Foundation Model (GeoFM)** approach
- for a “Decoding the Field” challenge

In other words: you’re diagramming the *system described by the documentation*, not the structure of a software implementation.

##### How to extract the architecture from the PDF (your real “source of truth”)
Because there is no code, the key step is to mine the PDF for:
##### Inputs / data sources
- Satellite imagery? Multispectral? SAR? Time series? Field boundaries? Labels?
##### Preprocessing
- Tiling/chipping, resampling, normalization, cloud masking, band selection, temporal stacking, etc.
##### Modeling approach
- Which GeoFM? Frozen vs fine-tuned? Any adapters/LoRA? Decoder head?
##### Training loop & losses
- Objective (classification/segmentation/regression), loss functions, augmentations
##### Evaluation
- Metrics, cross-validation split, leaderboard evaluation format
##### Inference / submission format
- Batch inference pipeline, post-processing, formatting outputs
##### Compute + tooling
- GPU/TPU, framework (PyTorch, Lightning), experiment tracking (W&B), artifact storage, etc.

**Practical instruction:** skim the PDF and create a one-page bullet list with sections:
- Data → Preprocess → Model → Train → Evaluate → Infer → Deliver

For this kind of project, you want to explicitly show *both*:
##### Artifact flow (models/metrics/submissions)

- Data sources → Preprocessing → Train dataset
- Train dataset → Training → Checkpoints
- Checkpoints → Inference
- Inference → Submission artifact
- Validation → Metrics → Model selection (feedback loop)

- Metrics / error analysis → Preprocessing tweaks / model tweaks

This reflects how these challenge solutions are actually built.

##### Architectural patterns/design principles to highlight (GeoML specific)
- **“Foundation model + task-specific decoder”** architecture
- **Separation of offline preprocessing vs online inference**
- **Reproducible experiments** (data versioning, fixed splits, checkpointing)
- **Geospatial leakage prevention** (spatially-aware splits)
- **Patch-based processing** (tile/chip) due to large rasters

These are core to “Decoding the Field” style solutions and should be visually encoded.

##### Diagramming guidance: make it detailed and componentized (don’t overthink)
Because the repo contains only documentation, your goal is to **over-separate** into components and label them clearly. Use consistent visual semantics:

- External data sources, compute environment, outputs/submission
- End-to-end ML flow from ingestion to submission
- GeoFM encoder + decoder head + losses + outputs

Since you only have:
- `Complete-project-doc.pdf` → treat as the **architecture spec**

- “Architecture derived from Complete-project-doc.pdf”
- If the PDF includes specific model names, dataset names, metrics, or steps, use those exact terms in labels.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: Context (Conceptual)
  %% =========================
  subgraph CTX["Context Diagram (Conceptual)"]
    direction TB

    DocSpec["Architecture Spec (PDF)"]:::doc
    ReadmeViz["High-level Visuals (README images)"]:::doc

    subgraph Ext["External Inputs / Challenge Environment"]
      direction TB
      RawProviders["Raw Imagery Provider(s)\n(e.g., Sentinel/Landsat/SAR)"]:::external
      LabelSource["Label Source / Ground Truth\n(field boundaries, crop labels)"]:::external
      MetaSource["Metadata\n(CRS, georeferencing, timestamps)"]:::external
      Leaderboard["Challenge Platform / Leaderboard"]:::external
    end

    subgraph Runtime["Runtime / Compute Environment"]
      direction TB
      TrainEnv["Training Environment\n(GPU/Cloud)"]:::compute
      InferEnv["Inference Environment\n(Batch runner)"]:::compute
      Tooling["Frameworks & Geo Tooling\n(PyTorch, GDAL/rasterio, etc.)"]:::compute
      OptionalDocker["Optional: Containerization\n(Docker)"]:::compute
    end

    subgraph Outputs["Outputs"]
      direction TB
      Submission["Submission Artifact\n(CSV/JSON/Geo outputs)"]:::artifact
      Reports["Metrics / Results Summary"]:::artifact
    end

    DocSpec -->|"drives"| CTXNote["Architecture derived from documentation\n(no executable code in repo)"]:::note
    ReadmeViz -->|"aligns_with"| CTXNote

    RawProviders -->|"imagery"| TrainEnv
    LabelSource -->|"labels"| TrainEnv
    MetaSource -->|"spatial_metadata"| TrainEnv

    TrainEnv -->|"best_model + outputs"| Submission
    TrainEnv -->|"metrics"| Reports
    Submission -->|"uploaded_to"| Leaderboard

    Tooling -->|"used_by"| TrainEnv
    Tooling -->|"used_by"| InferEnv
    OptionalDocker -.->|"optional"| TrainEnv
  end

  %% =========================
  %% Diagram 2: End-to-End ML / MLOps Pipeline
  %% =========================
  subgraph PIPE["End-to-End GeoML Pipeline (Data → Preprocess → Train → Infer → Deliver)"]
    direction TB

    subgraph DL["A) Data Layer"]
      direction TB
      ImageryProviders["Raw Imagery Provider(s)"]:::external
      GroundTruth["Labels / Ground Truth"]:::external
      GeoMeta["Metadata (CRS, timestamps)"]:::external

      RawStorage[("Raw Dataset Storage\n(local disk / cloud bucket / archive)")]:::storage
      DatasetVersioning[("Dataset Versioning (optional)\nDVC / Git LFS / dataset snapshots")]:::storage

      ImageryProviders -->|"raw_rasters"| RawStorage
      GroundTruth -->|"label_files"| RawStorage
      GeoMeta -->|"metadata_records"| RawStorage
      RawStorage -.->|"versioned_by"| DatasetVersioning
    end

    subgraph PP["B) Geospatial Preprocessing (Offline)"]
      direction TB

      CRSNorm["Reprojection / CRS Normalization"]:::process
      Coreg["Spatial Alignment / Co-registration"]:::process
      CloudMask["Cloud/Shadow Masking\n(if optical)"]:::process
      BandNorm["Band Selection + Normalization"]:::process
      Tiling["Tiling / Chipping into Patches"]:::process
      TemporalAgg["Temporal Aggregation / Stacking\n(if time series)"]:::process
      SplitBuilder["Spatially-aware Train/Val/Test Split Builder"]:::process
      Augment["Data Augmentation"]:::process

      LeakNote["Geospatial consistency constraints:\nprevent spatial leakage"]:::note

      RawStorage -->|"GeoTIFFs + labels + metadata"| CRSNorm
      CRSNorm --> Coreg
      Coreg --> CloudMask
      CloudMask --> BandNorm
      BandNorm --> Tiling
      Tiling --> TemporalAgg
      TemporalAgg --> SplitBuilder
      SplitBuilder --> Augment
      SplitBuilder --> LeakNote
    end

    subgraph DS["C) Prepared Datasets"]
      direction TB
      TrainSet[("Train Dataset\n(patch tensors + labels)")]:::storage
      ValSet[("Validation Dataset\n(patch tensors + labels)")]:::storage
      TestSet[("Test Dataset\n(patch tensors)")]:::storage

      Augment -->|"training_patches"| TrainSet
      SplitBuilder -->|"validation_patches"| ValSet
      SplitBuilder -->|"test_patches"| TestSet
    end

    subgraph M["D) Model (Foundation Encoder + Task Head)"]
      direction TB
      GeoFM["GeoFM Encoder (Pretrained)\n(frozen or fine-tuned)"]:::model
      Decoder["Decoder / Task Head\n(segmentation/classification/regression)"]:::model
      Preds["Predictions\n(logits/masks/values)"]:::model

      TrainSet -->|"patch_tensors"| GeoFM
      GeoFM -->|"features"| Decoder
      Decoder -->|"outputs"| Preds
    end

    subgraph TR["E) Training & Experimentation"]
      direction TB
      DataLoader["Dataloader / Batching\n(multi-band, temporal)"]:::runner
      TrainLoop["Training Loop\n(loss + optimizer + scheduler)"]:::runner
      Metrics["Evaluation Metrics\n(on validation split)"]:::process
      Tracking[("Experiment Tracking\n(optional: W&B/MLflow/logs)")]:::storage
      Checkpoints[("Checkpointing / Model Registry\n(best + latest)")]:::storage
      ModelSelect["Model Selection\n(best checkpoint)"]:::process
      ErrorAnalysis["Error Analysis / Iteration"]:::process

      TrainSet -->|"batches"| DataLoader
      ValSet -->|"val_batches"| DataLoader
      DataLoader -->|"train_batches"| TrainLoop
      Preds -.->|"val_predictions"| Metrics
      TrainLoop -->|"updates_weights"| GeoFM
      TrainLoop -->|"updates_weights"| Decoder
      TrainLoop -->|"writes"| Checkpoints
      Metrics -->|"logs"| Tracking
      Metrics -->|"selects"| ModelSelect
      ModelSelect -->|"pins_best"| Checkpoints

      Metrics -->|"feedback_loop"| ErrorAnalysis
      ErrorAnalysis -.->|"tune_preprocess"| PP
      ErrorAnalysis -.->|"tune_model"| M
    end

    subgraph INF["F) Inference + Delivery (Challenge Submission)"]
      direction TB
      InferRunner["Batch Inference Runner\n(over tiles/regions)"]:::runner
      Stitching["Stitch / Mosaic back to geospatial grid\n(if segmentation)"]:::process
      PostProc["Post-processing\n(threshold/smoothing/polygonization)"]:::process
      Exporter["Exporter\n(required submission format)"]:::process
      SubmissionArtifact[("Submission File\n(CSV/JSON/Geo outputs)")]:::artifact

      Checkpoints -->|"best_checkpoint"| InferRunner
      TestSet -->|"test_patches"| InferRunner
      InferRunner -->|"tile_predictions"| Stitching
      Stitching -->|"mosaic_predictions"| PostProc
      PostProc -->|"final_predictions"| Exporter
      Exporter -->|"submission"| SubmissionArtifact
    end

    %% Cross-links (artifacts)
    TrainLoop -->|"training_predictions"| Preds
    ValSet -->|"validation_data"| Metrics
    SubmissionArtifact -->|"upload"| LeaderboardNode["Challenge Platform / Leaderboard"]:::external
  end

  %% =========================
  %% Diagram 3: Model Internals (Conceptual)
  %% =========================
  subgraph MODEL["Model Internals (GeoFM + Decoder + Losses)"]
    direction TB

    InputPatch["Input Patch Tensor\n(BxCxHxW, optional time dimension)"]:::process
    PretrainedWeights[("Pretrained Weights\n(GeoFM checkpoint)")]:::storage

    Encoder2["GeoFM Encoder"]:::model
    Adapter["Optional Adapters\n(LoRA / fine-tune blocks)"]:::model
    Features["Latent Features / Tokens"]:::model

    Head["Task Decoder Head\n(seg/cls/reg)"]:::model
    Losses["Loss Functions\n(task-dependent)"]:::process
    Optim["Optimizer + Scheduler"]:::runner

    Output2["Model Output\n(logits/masks/values)"]:::model

    InputPatch --> Encoder2
    PretrainedWeights -->|"initialize"| Encoder2
    Encoder2 -->|"features"| Adapter
    Adapter --> Features
    Features --> Head
    Head --> Output2

    Output2 -->|"compare_to_labels"| Losses
    Losses -->|"backprop"| Optim
    Optim -->|"update"| Adapter
    Optim -->|"update_optional"| Head
    Optim -.->|"update_optional"| Encoder2
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click DocSpec "https://github.com/amandeva/amini-geofm-decoding-the-field-challenge/blob/main/Complete-project-doc.pdf"
  click ReadmeViz "https://github.com/amandeva/amini-geofm-decoding-the-field-challenge/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px;
  classDef doc fill:#F3F4F6,stroke:#374151,color:#111827,stroke-width:1px;
  classDef storage fill:#DBEAFE,stroke:#1D4ED8,color:#0B1220,stroke-width:1px;
  classDef process fill:#FFEDD5,stroke:#C2410C,color:#0B1220,stroke-width:1px;
  classDef model fill:#EDE9FE,stroke:#6D28D9,color:#0B1220,stroke-width:1px;
  classDef runner fill:#D1FAE5,stroke:#047857,color:#0B1220,stroke-width:1px;
  classDef artifact fill:#DCFCE7,stroke:#16A34A,color:#0B1220,stroke-width:1px;
  classDef compute fill:#FEF3C7,stroke:#B45309,color:#0B1220,stroke-width:1px;
  classDef note fill:#FFF7ED,stroke:#9A3412,color:#0B1220,stroke-dasharray: 4 3;
```
