# koushik9010/nativeanimalbd architecture

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

- Interactive diagram: https://gitdiagram.com/koushik9010/nativeanimalbd
- Repository: https://github.com/koushik9010/nativeanimalbd

## Overview

1. **Repository purpose**
   NativeAnimalBD is not an application codebase; it is a **curated image dataset repository** for Bangladeshi native animals. Its architecture is centered on **data organization, distribution, and citation**, rather than runtime services or executable components.

2. **Core asset model**
   The primary asset is a **hierarchical image corpus** of **8,000 images** arranged for computer vision and classification experiments. The hierarchy is two-level: **5 taxonomic super-classes** and **5 subclasses per super-class**, with **400 images per subclass**.

3. **Top-level dataset partitions**
   The dataset is split into five main branches:
   - **Aves**
   - **Mammals**
   - **Insecta**
   - **Reptiles**
   - **Fish**
   
   Each branch is meant to act as an independently distributable unit, and the README notes that the complete dataset is published as **separate compressed files per main class**.

4. **Subclass structure and semantic boundary**
   Within each main class, images are further grouped into species-level subclasses. Examples include:
   - Aves: Heron, Kingfisher, Magpie, Sparrow, Parrot
   - Mammals: Asian_Elephant, Indian_Leopard, Royal_Bengal_Tiger, Spotted_Deer, Wild_Boar
   - Insecta: Ants, Bee, Butterfly, Dragonfly, Grasshopper
   - Reptiles: Crocodile, Gharial, Lizard, Snake, Turtle
   - Fish: Byen, Koi, Sing, Taki, Tengra

   This hierarchy is the key architectural feature for downstream labeling and benchmarking.

5. **Data source boundary**
   The repository itself does not appear to store or generate the images directly in this checkout. Instead, it acts as a **distribution and documentation layer** for the dataset, while the actual image files are hosted externally on **Zenodo**. That makes Zenodo the main storage/infrastructure boundary for retrieval.

6. **Fish-class exception**
   A notable architectural constraint is that the **Fish images are not redistributed in this repository**. Users are instructed to obtain them from the **BDINDIGENOUSFISH2019** dataset. This creates a cross-dataset dependency: NativeAnimalBD is partially self-contained, but the full hierarchy requires an external source for one branch.

7. **Intended workflow / data flow**
   The implied data flow is:
   **Zenodo download → extract class archives → use hierarchical folder labels for training/evaluation**.
   The folder structure is the authoritative label source, so consumers likely rely on directory names rather than a separate annotation file.

8. **Research and benchmarking role**
   The dataset is designed for **hierarchical image classification**, **computer vision**, **deep learning**, and **biodiversity informatics**. Architecturally, this means the hierarchy is intentional: it supports experiments where models predict either coarse classes, fine subclasses, or both levels.

9. **Distribution and reproducibility**
   The dataset is versioned and citable through **Zenodo DOI 10.5281/zenodo.18729571**, which is the stable distribution endpoint. This is important for reproducibility: experiments can reference a persistent artifact rather than an ad hoc file share.

10. **Licensing boundary**
    The repository documents that images were collected from **Unsplash and Pexels** for non-fish classes, and users must comply with those platforms’ licenses. So the legal boundary is split by source: the dataset is a curated aggregation, not a single-origin asset pack.

11. **Repository content scope**
    Based on the tree provided, the repo currently contains only the **README documentation**. That means the repository’s architectural surface is minimal: it defines the dataset schema, distribution instructions, provenance, and citation metadata, but not preprocessing code, training code, or annotation tooling.

12. **What to draw in an architecture diagram**
    An accurate diagram should show:
    - a **documentation/metadata layer** in the repo
    - an **external Zenodo distribution store**
    - the **hierarchical dataset structure** as the central data model
    - an **external dependency for Fish** via BDINDIGENOUSFISH2019
    - consumers such as **ML training/evaluation workflows**
    
    The main boundary is between the lightweight repository documentation and the externally hosted image archives it describes.

Main entry points: [`README.md`](https://github.com/koushik9010/nativeanimalbd/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_readme["README<br/>docs<br/>[README.md]"]
end

subgraph group_dataset["Dataset model"]
  node_dataset_root[("NativeAnimalBD<br/>dataset")]
  node_coarse_labels["5 classes<br/>schema"]
  node_aves["Aves<br/>image-class"]
  node_mammals["Mammals<br/>image-class"]
  node_insecta["Insecta<br/>image-class"]
  node_reptiles["Reptiles<br/>image-class"]
  node_fish["Fish<br/>image-class"]
  node_subclasses["Species folders<br/>label-hierarchy"]
end

subgraph group_external["External sources"]
  node_zenodo[("Zenodo<br/>archive-host")]
  node_doi["DOI<br/>citation-id"]
  node_fish_source[("BDINDIGENOUSFISH2019<br/>external-dataset")]
  node_unsplash["Unsplash<br/>source"]
  node_pexels["Pexels<br/>source"]
end

subgraph group_use["Consumers"]
  node_training(("Training<br/>ml-workflow"))
  node_benchmarking(("Benchmarking<br/>ml-workflow"))
end

node_readme -->|"describes"| node_dataset_root
node_readme -->|"download"| node_zenodo
node_readme -->|"cites"| node_doi
node_readme -->|"provenance"| node_unsplash
node_readme -->|"provenance"| node_pexels
node_dataset_root -->|"organized as"| node_coarse_labels
node_coarse_labels -->|"includes"| node_aves
node_coarse_labels -->|"includes"| node_mammals
node_coarse_labels -->|"includes"| node_insecta
node_coarse_labels -->|"includes"| node_reptiles
node_coarse_labels -->|"includes"| node_fish
node_aves -->|"refines"| node_subclasses
node_mammals -->|"refines"| node_subclasses
node_insecta -->|"refines"| node_subclasses
node_reptiles -->|"refines"| node_subclasses
node_fish -->|"depends on"| node_fish_source
node_zenodo -->|"hosts"| node_dataset_root
node_doi -->|"resolves to"| node_zenodo
node_training -->|"consumes"| node_dataset_root
node_benchmarking -->|"evaluates"| node_dataset_root
node_benchmarking -->|"uses"| node_coarse_labels
node_benchmarking -->|"uses"| node_subclasses

click node_readme "https://github.com/koushik9010/nativeanimalbd/blob/main/README.md"

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_readme toneBlue
class node_dataset_root,node_coarse_labels,node_aves,node_mammals,node_insecta,node_reptiles,node_fish,node_subclasses toneAmber
class node_zenodo,node_doi,node_fish_source,node_unsplash,node_pexels toneMint
class node_training,node_benchmarking toneRose
```

## Components

### Repository

Lightweight documentation and metadata layer.

- [README](https://github.com/koushik9010/nativeanimalbd/blob/main/README.md): docs · Primary repository content and dataset instructions. · `README.md`

### Dataset model

Hierarchical image corpus organized for classification.

- **NativeAnimalBD**: dataset · Curated 8k-image corpus with hierarchical labels.
- **5 classes**: schema · Top-level taxonomy used as the main partitioning scheme.
- **Aves**: image-class · Bird branch; distributed as its own archive.
- **Mammals**: image-class · Mammal branch; distributed as its own archive.
- **Insecta**: image-class · Insect branch; distributed as its own archive.
- **Reptiles**: image-class · Reptile branch; distributed as its own archive.
- **Fish**: image-class · Fish branch; not redistributed in this checkout.
- **Species folders**: label-hierarchy · Second-level species labels under each main class.

### External sources

Hosting, provenance, and cross-dataset dependencies.

- **Zenodo**: archive-host · Stable distribution endpoint for the dataset archives.
- **DOI**: citation-id · Persistent citation for the published dataset artifact.
- **BDINDIGENOUSFISH2019**: external-dataset · Required source for the fish branch.
- **Unsplash**: source · Image provenance source for non-fish classes.
- **Pexels**: source · Image provenance source for non-fish classes.

### Consumers

Downstream research and benchmarking workflows.

- **Training**: ml-workflow · Uses folder names as authoritative labels for model training.
- **Benchmarking**: ml-workflow · Supports hierarchical classification experiments and evaluation.

## Connections

- README → NativeAnimalBD: describes · The README defines the dataset structure and usage.
- README → Zenodo: download · Readers are directed to the Zenodo archive for retrieval.
- README → DOI: cites · The repository documents a persistent DOI for the release.
- README → Unsplash: provenance · Non-fish images are collected from Unsplash.
- README → Pexels: provenance · Non-fish images are collected from Pexels.
- NativeAnimalBD → 5 classes: organized as · The corpus is arranged into five super-classes.
- 5 classes → Aves: includes · Bird branch.
- 5 classes → Mammals: includes · Mammal branch.
- 5 classes → Insecta: includes · Insect branch.
- 5 classes → Reptiles: includes · Reptile branch.
- 5 classes → Fish: includes · Fish branch.
- Aves → Species folders: refines · Species-level folders sit beneath the branch.
- Mammals → Species folders: refines · Species-level folders sit beneath the branch.
- Insecta → Species folders: refines · Species-level folders sit beneath the branch.
- Reptiles → Species folders: refines · Species-level folders sit beneath the branch.
- Fish → BDINDIGENOUSFISH2019: depends on · Fish images are obtained from the external fish dataset.
- Zenodo → NativeAnimalBD: hosts · Primary distributed archives are published on Zenodo.
- DOI → Zenodo: resolves to · The DOI identifies the archived dataset release.
- Training → NativeAnimalBD: consumes · Models use the folder hierarchy as label input.
- Benchmarking → NativeAnimalBD: evaluates · The hierarchy supports coarse- and fine-grained experiments.
- Benchmarking → 5 classes: uses · Coarse classification can target the top-level classes.
- Benchmarking → Species folders: uses · Fine-grained classification can target species folders.
