# gratheon/models-queen-bee-detector architecture

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

- Interactive diagram: https://gitdiagram.com/gratheon/models-queen-bee-detector
- Repository: https://github.com/gratheon/models-queen-bee-detector

## Overview

1. **What this repo is**
   - This is a single-purpose ML repository for a **queen bee object detector**.
   - The repo centers on a trained YOLO-based model plus the tooling to **download datasets, merge labels, train, evaluate, export, and serve inference over HTTP**.

2. **Top-level architecture**
   - The repo is mostly **file and script driven**, not a multi-service application.
   - Main boundaries are:
     - **data ingestion/normalization** in `scripts/`
     - **model training/evaluation/export** in `scripts/`
     - **runtime inference API** in `src/server.py`
     - **artifact storage** in `datasets/`, `weights/`, and `exports/`

3. **Dataset subsystem**
   - `datasets/catalog.yaml` is the machine-readable source of truth for dataset candidates and metadata.
   - `scripts/download_dataset.py` pulls Roboflow datasets into local folders.
   - `scripts/merge_queen_dataset.py` combines multiple source datasets into one normalized **single-class `queen`** dataset, preserving negative/background images and converting polygon annotations to bounding boxes.
   - This is the main data-preparation boundary: raw external datasets come in, a normalized training dataset comes out.

4. **Model training pipeline**
   - `scripts/train.py` is the training entry point, using **Ultralytics YOLOv8** with a baseline `yolov8n.pt` backbone.
   - Training reads a dataset YAML generated by the merge step and writes run artifacts under `runs/`.
   - The README indicates the current baseline was trained at `imgsz=512`, `epochs=60`, and is optimized for queen detection specifically.

5. **Evaluation pipeline**
   - `scripts/evaluate.py` evaluates saved weights against a chosen dataset split, typically `test`.
   - The expected outputs are standard detection metrics: precision, recall, mAP50, and mAP50-95.
   - This is a separate validation boundary from training, which makes it easy to compare candidate weights without retraining.

6. **Export pipeline**
   - `scripts/export_model.py` converts the trained PyTorch weights into deployable formats such as **ONNX** and optionally **TensorFlow.js**.
   - The repo’s intended browser path is ONNX plus `onnxruntime-web`.
   - Export artifacts are intentionally kept out of source control, which reinforces the separation between model training and deployment packaging.

7. **HTTP inference service**
   - `src/server.py` exposes the model as a lightweight HTTP service.
   - The service supports:
     - `GET /health` for readiness/weight presence
     - `GET /` for a simple upload form
     - `POST /` and `POST /detect` for multipart image inference
   - The request path is image upload → model inference → detection JSON response, with optional confidence and IoU thresholds.

8. **Runtime configuration and observability**
   - The service behavior is controlled by environment variables such as:
     - model weight path
     - max upload size
     - confidence threshold
     - IoU threshold
   - Logging is integrated through the shared Gratheon logging library and supports **request-scoped request IDs**.
   - If configured, logs can be exported to an **OTLP/OpenTelemetry collector**, so observability is an external runtime boundary rather than built into the model logic.

9. **Deployment and packaging**
   - `Dockerfile`, `docker-compose.yml`, and `docker-compose.dev.yml` package the inference service for containerized use.
   - `restart.sh` suggests a simple operational restart workflow.
   - `.github/workflows/deploy.yml` indicates automated deployment from CI/CD.
   - The repo is therefore deployable both as a local Python service and as a containerized runtime.

10. **Artifacts and persistence**
   - `weights/best.pt` is the checked-in reference model artifact.
   - `datasets/`, `weights/`, `exports/`, and `runs/` are treated as artifact directories, but only selected reference assets are committed.
   - The repo intentionally excludes large or environment-specific outputs like training runs, browser exports, and secrets.

11. **Testing boundary**
   - `tests/test_server_contract.py` is a contract test for the HTTP API.
   - Its presence implies the API shape is important and stabilized, especially around request/response behavior rather than internal model details.
   - This makes the inference service a clear externally consumed component.

12. **External dependencies that matter architecturally**
   - **Roboflow** is the upstream dataset source.
   - **Ultralytics YOLOv8** is the model/training framework.
   - **OpenTelemetry/OTLP** is used for optional tracing/log export.
   - A browser/web-app consumer is expected to call the HTTP service or consume exported ONNX/TFJS artifacts, but that frontend is outside this repo.

13. **Overall data flow**
   - External bee datasets are downloaded and normalized locally.
   - The merged dataset feeds YOLOv8 training.
   - Trained weights are evaluated, exported, and stored.
   - The `best.pt` artifact is then loaded by the HTTP service for live image detection.
   - The repo is therefore a compact **ML lifecycle repository** with a single production inference boundary and several offline preparation stages.

Main entry points: [`weights/best.pt`](https://github.com/gratheon/models-queen-bee-detector/blob/main/weights/best.pt) (Weights), [`datasets`](https://github.com/gratheon/models-queen-bee-detector/tree/main/datasets) (Datasets), [`scripts/train.py`](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/train.py) (Train), [`Dockerfile`](https://github.com/gratheon/models-queen-bee-detector/tree/main/Dockerfile) (Dockerfile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data["Data prep"]
  node_n_catalog["Dataset catalog<br/>metadata source<br/>[catalog.yaml]"]
  node_n_download["Download<br/>dataset fetcher"]
  node_n_merge["Merge queen<br/>data normalizer"]
  node_n_datasets[("Datasets<br/>artifact store")]
end

subgraph group_group_model["Model lifecycle"]
  node_n_train_cfg["Train config<br/>model config<br/>[queen_bee.yaml]"]
  node_n_train_primary["Primary config<br/>model config"]
  node_n_train["Train<br/>[train.py]"]
  node_n_eval["Evaluate<br/>metrics runner<br/>[evaluate.py]"]
  node_n_export["Export<br/>artifact packager<br/>[export_model.py]"]
  node_n_weights[("Weights<br/>model artifact<br/>[best.pt]")]
  node_n_exports[("Exports<br/>deployment artifacts")]
end

subgraph group_group_runtime["Serving"]
  node_n_server["HTTP server<br/>inference api<br/>[server.py]"]
  node_n_contract["Contract test<br/>api contract"]
end

subgraph group_group_ops["Packaging"]
  node_n_docker["Dockerfile<br/>container build"]
  node_n_compose["Compose<br/>runtime packaging<br/>[docker-compose.yml]"]
  node_n_compose_dev["Dev compose<br/>runtime packaging"]
  node_n_workflow["Deploy CI<br/>ci/cd workflow<br/>[deploy.yml]"]
end

node_n_catalog -->|"drives"| node_n_download
node_n_download -->|"writes"| node_n_datasets
node_n_datasets -->|"inputs"| node_n_merge
node_n_merge -->|"produces"| node_n_datasets
node_n_train_cfg -->|"configures"| node_n_train
node_n_train_primary -->|"configures"| node_n_train
node_n_datasets -->|"feeds"| node_n_train
node_n_train -->|"emits"| node_n_weights
node_n_weights -->|"evaluates"| node_n_eval
node_n_eval -.->|"validates"| node_n_weights
node_n_weights -->|"exports"| node_n_export
node_n_export -->|"writes"| node_n_exports
node_n_weights -->|"loads"| node_n_server
node_n_server -.->|"verified by"| node_n_contract
node_n_docker -->|"packages"| node_n_server
node_n_compose -->|"orchestrates"| node_n_docker
node_n_compose_dev -->|"orchestrates"| node_n_docker
node_n_workflow -->|"deploys"| node_n_compose
node_n_workflow -->|"builds"| node_n_docker

click node_n_catalog "https://github.com/gratheon/models-queen-bee-detector/blob/main/datasets/catalog.yaml"
click node_n_download "https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/download_dataset.py"
click node_n_merge "https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/merge_queen_dataset.py"
click node_n_datasets "https://github.com/gratheon/models-queen-bee-detector/tree/main/datasets"
click node_n_train_cfg "https://github.com/gratheon/models-queen-bee-detector/blob/main/configs/queen_bee.yaml"
click node_n_train_primary "https://github.com/gratheon/models-queen-bee-detector/blob/main/configs/queen_bee_primary.yaml"
click node_n_train "https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/train.py"
click node_n_eval "https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/evaluate.py"
click node_n_export "https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/export_model.py"
click node_n_weights "https://github.com/gratheon/models-queen-bee-detector/blob/main/weights/best.pt"
click node_n_exports "https://github.com/gratheon/models-queen-bee-detector/tree/main/exports"
click node_n_server "https://github.com/gratheon/models-queen-bee-detector/blob/main/src/server.py"
click node_n_contract "https://github.com/gratheon/models-queen-bee-detector/blob/main/tests/test_server_contract.py"
click node_n_docker "https://github.com/gratheon/models-queen-bee-detector/tree/main/Dockerfile"
click node_n_compose "https://github.com/gratheon/models-queen-bee-detector/blob/main/docker-compose.yml"
click node_n_compose_dev "https://github.com/gratheon/models-queen-bee-detector/blob/main/docker-compose.dev.yml"
click node_n_workflow "https://github.com/gratheon/models-queen-bee-detector/blob/main/.github/workflows/deploy.yml"

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_n_catalog,node_n_download,node_n_merge,node_n_datasets toneBlue
class node_n_train_cfg,node_n_train_primary,node_n_train,node_n_eval,node_n_export,node_n_weights,node_n_exports toneAmber
class node_n_server,node_n_contract toneMint
class node_n_docker,node_n_compose,node_n_compose_dev,node_n_workflow toneRose
```

## Components

### Data prep

Dataset cataloging, download, and normalization into a single-class queen dataset.

- [Dataset catalog](https://github.com/gratheon/models-queen-bee-detector/blob/main/datasets/catalog.yaml): metadata source · Machine-readable source of dataset candidates and labels. · `datasets/catalog.yaml`
- [Download](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/download_dataset.py): dataset fetcher · Pulls external Roboflow datasets into local storage. · `scripts/download_dataset.py`
- [Merge queen](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/merge_queen_dataset.py): data normalizer · Combines source datasets into a single-class queen dataset and converts annotations to boxes. · `scripts/merge_queen_dataset.py`
- [Datasets](https://github.com/gratheon/models-queen-bee-detector/tree/main/datasets): artifact store · Local dataset workspace and prepared training data. · `datasets`

### Model lifecycle

Training, evaluation, and export of the detector weights.

- [Train config](https://github.com/gratheon/models-queen-bee-detector/blob/main/configs/queen_bee.yaml): model config · Training presets for queen bee detector runs. · `configs/queen_bee.yaml`
- [Primary config](https://github.com/gratheon/models-queen-bee-detector/blob/main/configs/queen_bee_primary.yaml): model config · Alternate or baseline training configuration. · `configs/queen_bee_primary.yaml`
- [Train](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/train.py): yolov8 trainer · Ultralytics YOLOv8 training entry point using prepared dataset YAML. · `scripts/train.py`
- [Evaluate](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/evaluate.py): metrics runner · Scores saved weights on a chosen split and reports detection metrics. · `scripts/evaluate.py`
- [Export](https://github.com/gratheon/models-queen-bee-detector/blob/main/scripts/export_model.py): artifact packager · Converts trained weights to deployable formats such as ONNX and optional TFJS. · `scripts/export_model.py`
- [Weights](https://github.com/gratheon/models-queen-bee-detector/blob/main/weights/best.pt): model artifact · Checked-in reference detector weights and model outputs. · `weights/best.pt`
- [Exports](https://github.com/gratheon/models-queen-bee-detector/tree/main/exports): deployment artifacts · Exported runtime artifacts kept separate from source control. · `exports`

### Serving

HTTP inference service and its contract.

- [HTTP server](https://github.com/gratheon/models-queen-bee-detector/blob/main/src/server.py): inference api · Lightweight image upload and detection service. · `src/server.py`
- [Contract test](https://github.com/gratheon/models-queen-bee-detector/blob/main/tests/test_server_contract.py): api contract · Verifies the external HTTP request and response behavior. · `tests/test_server_contract.py`

### Packaging

Containerization, deployment automation, and operational helpers.

- [Dockerfile](https://github.com/gratheon/models-queen-bee-detector/tree/main/Dockerfile): container build · Builds the inference service container image. · `Dockerfile`
- [Compose](https://github.com/gratheon/models-queen-bee-detector/blob/main/docker-compose.yml): runtime packaging · Container definitions for local and development deployment. · `docker-compose.yml`
- [Dev compose](https://github.com/gratheon/models-queen-bee-detector/blob/main/docker-compose.dev.yml): runtime packaging · Development-oriented container composition. · `docker-compose.dev.yml`
- [Deploy CI](https://github.com/gratheon/models-queen-bee-detector/blob/main/.github/workflows/deploy.yml): ci/cd workflow · Automated deployment pipeline from GitHub Actions. · `.github/workflows/deploy.yml`

## Connections

- Dataset catalog → Download: drives · Dataset catalog determines which sources are fetched.
- Download → Datasets: writes · Downloaded raw datasets are stored locally.
- Datasets → Merge queen: inputs · Merged dataset builder consumes downloaded source data.
- Merge queen → Datasets: produces · Normalization outputs a consolidated queen dataset.
- Train config → Train: configures · Training preset guides YOLOv8 runs.
- Primary config → Train: configures · Alternate baseline configuration feeds training.
- Datasets → Train: feeds · Prepared dataset YAML and images are used for training.
- Train → Weights: emits · Training produces model checkpoints and best weights.
- Weights → Evaluate: evaluates · Saved weights are scored against a dataset split.
- Evaluate → Weights: validates · Evaluation confirms candidate model quality.
- Weights → Export: exports · Trained weights are converted into deployable formats.
- Export → Exports: writes · Export pipeline stores ONNX/TFJS artifacts.
- Weights → HTTP server: loads · HTTP service uses the reference detector weights at runtime.
- HTTP server → Contract test: verified by · Contract test locks down API behavior.
- Dockerfile → HTTP server: packages · Container image wraps the inference server.
- Compose → Dockerfile: orchestrates · Compose defines the runtime container setup.
- Dev compose → Dockerfile: orchestrates · Dev compose mirrors the service for local iteration.
- Deploy CI → Compose: deploys · CI/CD workflow supports automated deployment.
- Deploy CI → Dockerfile: builds · Deployment pipeline builds container artifacts.
