# Developer Guide

Technical reference for developers working on or extending the Wildlife Monitoring Dashboard.

## Architecture Overview

The application is a single-file Flask server (`dashboard.py`) with HTML/CSS/JS templates embedded as Python string constants. There is no separate frontend build step.

```
Browser  <──HTTP──>  Flask (dashboard.py)
                         │
                         ├── Model inference (PyTorch, EfficientNet V2-S)
                         ├── XAI pipeline (ScoreCAM, LIME, nearest neighbours)
                         ├── In-memory detection state
                         └── File-based XAI cache (_xai_cache/)
```

## Key Components

### Model & Data Loading (module level)

On startup, the following are loaded once:

- **Model**: `EfficientNet_V2_S_Weights` base with a custom 7-class classification head, loaded from `efficientnet_v2_wild_forest_animals.pt`.
- **ScoreCAM**: Targets the last convolutional layer (`model.features[-1]`).
- **LIME explainer**: `LimeImageExplainer` instance.
- **Dataset auto-download**: If `wild-forest-animals-and-person-1/` is missing, the Roboflow SDK downloads it automatically on startup.
- **Datasets**: `test_ds` and `train_ds` using `WildForestAnimalsDataset`, a custom `Dataset` class reading from the Roboflow-exported directory structure with `_classes.csv` label files.
- **Training features**: Pre-extracted feature vectors for all training images (used for nearest neighbour lookup). Stored as a normalised matrix `train_feats` for fast cosine similarity via matrix multiplication.

### Detection Simulation (`/api/simulate`)

Each call:
1. Picks a random image from `test_ds` and a random camera.
2. Runs model inference to get predicted class and confidence.
3. Creates a detection dict with a unique 8-char hex ID.
4. Saves the original image to `_xai_cache/<det_id>/original.png`.
5. Kicks off `compute_xai` in a **background thread** (serialised by `_xai_lock` to prevent GPU OOM).
6. Returns the detection as JSON.

### XAI Pipeline (`compute_xai`)

Produces all explanation artefacts for a detection and writes them to `_xai_cache/<det_id>/`:

| File | Method |
|---|---|
| `original.png` | Raw input image (224x224) |
| `chart.png` | Matplotlib probability bar chart (kept for potential offline use) |
| `scorecam.png` | ScoreCAM heatmap overlay |
| `lime1.png` | LIME explanation for top-1 predicted class |
| `lime2.png` | LIME explanation for top-2 predicted class |
| `contrastive.png` | Contrastive LIME (top-1 vs top-2) |
| `nb1.png`, `nb2.png`, `nb3.png` | Three nearest training neighbours |
| `meta.json` | Metadata: predictions, probabilities, LIME class labels, neighbour info |

The function is **idempotent** — it checks for `meta.json` existence before computing. A `threading.Lock` (`_xai_lock`) ensures only one computation runs at a time to avoid GPU memory exhaustion.

### Background Pre-computation

When a detection is simulated, XAI computation starts immediately in a background thread. The `/api/xai/<det_id>` endpoint waits on a `threading.Event` for that detection. This means:

- If the user clicks a detection after a few seconds, XAI is likely already cached.
- If they click immediately, the request blocks until computation finishes.
- If somehow no background thread was started, it falls back to synchronous computation.

### API Endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/` | GET | Home page (map + sidebar) |
| `/det/<det_id>` | GET | Detection detail page |
| `/cam/<cam_id>` | GET | Camera feed page |
| `/api/simulate` | POST | Simulate a new detection |
| `/api/xai/<det_id>` | GET | Get XAI results (triggers computation if needed) |
| `/api/detections` | GET | List all detections |
| `/api/verify/<det_id>` | POST | Verify or correct a detection |
| `/map.webp` | GET | Serve the map image |
| `/xai/<det_id>/<filename>` | GET | Serve cached XAI images |

### HTML Templates

Three template constants are defined as raw Python f-strings (`r"""..."""`):

- `HOME_HTML` — fullscreen map, camera markers, sidebar with chart/filters/list, auto-simulation JS loop.
- `DETAIL_HTML` — verification bar, XAI carousel with left/right navigation, HTML/CSS probability chart.
- `CAM_HTML` — responsive grid of detection cards for a single camera.

Templates use Jinja2 syntax (via Flask's `render_template_string`) and receive context variables like `cameras`, `class_names`, `det`, etc.

### In-Memory State

All detection state is held in the `detections` Python list. This means:

- State is lost on server restart.
- There is no database.
- This is intentional for a demonstration/prototype.

## Extending the Application

### Adding a new XAI method

1. Add the computation logic inside `compute_xai()`, saving the output as a PNG in the `out` directory.
2. Add any relevant metadata to the `meta` dict.
3. Add a new slide entry in the `slides` array in `DETAIL_HTML`'s JavaScript.

### Adding a new species

1. Add the class name to `CLASS_NAMES`.
2. Add an emoji to `SPECIES_ICON`.
3. Retrain the model with the new class and update `efficientnet_v2_wild_forest_animals.pt`.

### Adding or moving cameras

Edit the `CAMERAS` dict. The `px` and `py` values are percentages relative to the map image dimensions (left/top).

### Persisting detections

To add persistence, replace the `detections` list with a database (e.g. SQLite). Key fields per detection: `id`, `idx`, `cam`, `pred`, `conf`, `time`, `verified`, `manual`. The `_xai_cache` directory already provides file-based persistence for XAI artefacts.

## Dependencies

Core runtime dependencies (see `pyproject.toml`):

| Package | Purpose |
|---|---|
| `flask` | Web framework |
| `torch`, `torchvision` | Model inference and image transforms |
| `grad-cam` | ScoreCAM implementation |
| `lime` | LIME explainer |
| `scipy` | Required by LIME internals |
| `matplotlib` | Probability chart generation |
| `Pillow` (via torchvision) | Image I/O |
| `scikit-image` (via lime) | `mark_boundaries` for LIME visualisation |

## Running in Development

```bash
uv run python dashboard.py
```

Flask runs in debug mode with auto-reload on port 5000. The `_xai_cache/` directory can be deleted at any time to force recomputation of all explanations.