2. Architecture & Data Flow

┌─────────────────────────────────────────────────────────────┐
│                     DATA FLOW                                │
│                                                              │
│  data/raw/{cattle,buffalo}/<breed>/*.jpg                     │
│        ↓                                                     │
│  data_pipeline.prepare_splits() → data/splits/*.csv          │
│        ↓                                                     │
│  CattleBuffaloDataset → DataLoader (mixing OFF by default)   │
│        ↓                                                     │
│  ┌─ EfficientNet-Lite backbone (stages 0..6) ─┐             │
│  │   stem → [stage0..3] → CBAM → [stage4..6] → head        │
│  └──────────────────────────────────────────────┘            │
│        ↓ AdaptiveAvgPool2d(1) → flatten(1)                   │
│        ↓ (1280-dim pooled feature vector)                    │
│  ┌─────┼─────────┬──────────────┬───────────────────┬──────────────┐
│  ↓     ↓         ↓              ↓                   ↓              │
│ binary_head  cattle_head  buffalo_head   projection_head  trait_heads│
│  (→2)        (→57)        (→18)          (→128)           (→75)      │
│        ↓                                                           │
│  masked_loss: w_bin*CE + w_cat*CE + w_buf*CE + w_trait*BCE         │
│               (+ τ·log(prior) logit adjustment, OFF default)       │
│               (+ λ·SupCon(projection embedding))                   │
│        ↓                                                     │
│  outputs/checkpoints/<backbone>_phase{N}_best_<runid>.pt           │
│        ↓                                                           │
│  Energy-based OOD Filtering (rejects energy > calibrated threshold)   │
│        ↓                                                           │
│  outputs/export/portable/<backbone>_<...>_<runid>/                 │
└────────────────────────────────────────────────────────────────────┘

Inference Flow

Image → Resize(260) → CenterCrop(260) → ToTensor()
     → model.forward() → {binary, cattle, buffalo, features, embedding, traits}
     → Energy OOD check (abort if OOD)
     → soft routing: p(species)·softmax(head) over all 68 breeds → top-k

Client Capture Flow (React, zero-crop)

The web client normalises every input to the model input size before upload, so the server-side Resize(260) → CenterCrop(260) becomes an identity pass-through and no part of the animal is discarded:

Original image (EXIF applied)
  → 260×260 canvas: stretch (default) | pad · ImageNet mean | pad · ambient blur | pad · black
  → optional 1:1 manual framing (pan on both axes) applied to the ORIGINAL
  → POST /api/predict (260×260 JPEG + original filename)
  → ResultWorkspace (Big-4 species / breed / gender / age, read-only)
  → quality gate + OOD explainer (blur/exposure/framing, trilingual tips)
  → Farmer advisory / breed encyclopedia tabs + printable report card
  → herd session log → CSV / JSON / ODT export

See Web Application for the full client architecture and Manual OOD calibration for the folder-based threshold workflow.

---

3. Directory Map

Mini Project/
├── src/                        # Core ML package (run as python -m src.<module>)
│   ├── __init__.py
│   ├── config.py               # All hyperparameters & paths
│   ├── data_pipeline.py        # Dataset, splits, augmentation, DataLoaders
│   ├── model.py                # BreedClassifier (backbone + attention + heads)
│   ├── cbam.py                 # CBAM & SE attention modules
│   ├── efficientnet_lite.py    # EfficientNet-Lite{2,4} architecture
│   ├── train.py                # 2-phase training (+opt-in QAT, distillation), AMP, auto-export
│   ├── metrics.py              # evaluate_epoch() — per-head accuracy + F1
│   ├── evaluate.py             # Full evaluation with confusion matrices
│   ├── export.py               # ONNX, TFLite INT8, ONNX INT8, float16, portable export
│   ├── parity_check.py         # fp32 vs mobile-artifact parity gate
│   └── verify.py               # Quick architecture sanity check
├── colab/
│   ├── cattle_buffalo_trainer.py   # Colab training script (percent-format)
│   ├── cattle_buffalo_trainer.ipynb # Jupyter notebook (auto-generated)
│   ├── convert_to_notebook.py  # .py → .ipynb converter
│   └── README.md               # Colab setup instructions

├── data/
│   ├── raw/                    # Source images: raw/{cattle,buffalo}/<breed>/*.jpg
│   └── splits/                 # Generated: train.csv, val.csv, test.csv, *_classes.json
├── outputs/
│   ├── checkpoints/            # Training checkpoints (*.pt)
│   ├── export/                 # ONNX/INT8/float16 exports
│   │   └── portable/           # Self-contained model bundles
│   ├── metrics/                # Evaluation JSON + confusion matrix PNGs
│   └── memory/                 # Mem0 ChromaDB storage
├── scripts/                    # Colab archive creators, app asset prep
├── create_training_zip.py      # Creates lightweight standalone training package
├── setup.sh                    # Shell script helper for environment setup
├── setup_venv.py               # Automated virtual environment setup script
├── .gitignore                  # Git ignore rules (includes outputs, venv, cache; tracks memory/)
├── efficientnet_lite{2,4}.pth  # Pretrained ImageNet backbone weights
├── requirements.txt            # Python dependencies
└── setup.sh / setup_venv.py    # Environment setup

---