# surveytools/scoutbot-two architecture

> Architecture diagram of the GitHub repository surveytools/scoutbot-two, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/surveytools/scoutbot-two
- Repository: https://github.com/surveytools/scoutbot-two

## Overview

Scoutbot is a YOLOv8-based wildlife detection pipeline for aerial-survey imagery. The principal workflow is to submit an image through the CLI or Python API, obtain a configured model, run detection, and return a wildlife score plus localized detections. The repository also supports model fetching and registration, Core ML export, resumable multiprocess batches, and observer-based performance events. The graph reflects documented capabilities, but several internal call details are not visible in the excerpts; those links are omitted or marked unverified rather than inferred.

Main entry points: [`scoutbot/__init__.py`](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/__init__.py) (Pipeline API), [`scoutbot/model_store.py`](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/model_store.py) (Model fetching), [`scoutbot/_observability.py`](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/_observability.py) (Runtime events), [`scoutbot/scoutbot.py`](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/scoutbot.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Detection workflow"]
  node_cli["CLI commands<br/>[scoutbot.py]"]
  node_pipeline["Pipeline API<br/>[__init__.py]"]
  node_detector["YOLO detector<br/>[main.py]"]
  node_results["Scores and detections<br/>[__init__.py]"]
end

subgraph group_models["Models and registry"]
  node_model_store["Model fetching<br/>[model_store.py]"]
  node_model_cache[("Model cache<br/>[paths.py]")]
  node_registry[("Model registry<br/>[__init__.py]")]
  node_registry_schema["Registry records<br/>[schema.py]"]
  node_model_source(("Model source"))
  node_coreml_export["Core ML export<br/>[model_store.py]"]
end

subgraph group_batch["Batch processing"]
  node_batch_resume["Resume orchestration<br/>[_batch_mp.py]"]
end

subgraph group_telemetry["Observability"]
  node_observer(("Observer"))
  node_observability["Runtime events<br/>[_observability.py]"]
end

node_user(("Image user"))

node_user -->|"runs command"| node_cli
node_cli -->|"calls pipeline"| node_pipeline
node_pipeline -->|"fetches model"| node_model_store
node_pipeline -.->|"uses detector"| node_detector
node_pipeline -->|"returns results"| node_results
node_model_store -->|"uses cache paths"| node_model_cache
node_model_store -->|"looks up and registers"| node_registry
node_registry -->|"converts records"| node_registry_schema
node_registry -->|"resolves registry path"| node_model_cache
node_model_source -->|"provides downloads"| node_model_store
node_model_store -->|"exports on demand"| node_coreml_export
node_cli -.->|"starts resumable batch"| node_batch_resume
node_batch_resume -->|"processes images"| node_pipeline
node_pipeline -->|"emits events"| node_observability
node_detector -->|"emits events"| node_observability
node_model_store -->|"emits events"| node_observability
node_observer -->|"receives events"| node_observability

click node_cli "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/scoutbot.py"
click node_pipeline "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/__init__.py"
click node_detector "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/tile_batched/main.py"
click node_results "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/__init__.py"
click node_model_store "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/model_store.py"
click node_model_cache "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/paths.py"
click node_registry "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/__init__.py"
click node_registry_schema "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/schema.py"
click node_coreml_export "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/model_store.py"
click node_batch_resume "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/_batch_mp.py"
click node_observability "https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/_observability.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_pipeline,node_detector,node_results,node_user toneBlue
class node_model_store,node_model_cache,node_registry,node_registry_schema,node_model_source,node_coreml_export toneAmber
class node_batch_resume toneMint
class node_observer,node_observability toneRose
```

## Components

### Detection workflow

- [CLI commands](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/scoutbot.py): `scoutbot/scoutbot.py`
- [Pipeline API](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/__init__.py): `scoutbot/__init__.py`
- [YOLO detector](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/tile_batched/main.py): `scoutbot/tile_batched/main.py`
- [Scores and detections](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/__init__.py): `scoutbot/__init__.py`

### Models and registry

- [Model fetching](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/model_store.py): `scoutbot/model_store.py`
- [Model cache](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/paths.py): `scoutbot/registry/paths.py`
- [Model registry](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/__init__.py): `scoutbot/registry/__init__.py`
- [Registry records](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/registry/schema.py): `scoutbot/registry/schema.py`
- **Model source**
- [Core ML export](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/model_store.py): `scoutbot/model_store.py`

### Batch processing

- [Resume orchestration](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/_batch_mp.py): `scoutbot/_batch_mp.py`

### Observability

- **Observer**
- [Runtime events](https://github.com/surveytools/scoutbot-two/blob/main/scoutbot/_observability.py): `scoutbot/_observability.py`

### Other components

- **Image user**

## Connections

- Image user → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Pipeline API: calls pipeline (evidence: `scoutbot/scoutbot.py`)
- Pipeline API → Model fetching: fetches model (evidence: `scoutbot/__init__.py`)
- Pipeline API → YOLO detector: uses detector
- Pipeline API → Scores and detections: returns results (evidence: `scoutbot/__init__.py`)
- Model fetching → Model cache: uses cache paths (evidence: `scoutbot/registry/paths.py`)
- Model fetching → Model registry: looks up and registers (evidence: `scoutbot/model_store.py`)
- Model registry → Registry records: converts records (evidence: `scoutbot/registry/__init__.py`)
- Model registry → Model cache: resolves registry path (evidence: `scoutbot/registry/__init__.py`)
- Model source → Model fetching: provides downloads (evidence: `scoutbot/model_store.py`)
- Model fetching → Core ML export: exports on demand (evidence: `scoutbot/model_store.py`)
- CLI commands → Resume orchestration: starts resumable batch (evidence: `scoutbot/_batch_mp.py`)
- Resume orchestration → Pipeline API: processes images (evidence: `scoutbot/_batch_mp.py`)
- Pipeline API → Runtime events: emits events (evidence: `scoutbot/__init__.py`)
- YOLO detector → Runtime events: emits events (evidence: `scoutbot/tile_batched/main.py`)
- Model fetching → Runtime events: emits events (evidence: `scoutbot/model_store.py`)
- Observer → Runtime events: receives events (evidence: `scoutbot/_observability.py`)