# birdnet-team/birdnet-analyzer architecture

> Architecture diagram of the GitHub repository birdnet-team/birdnet-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/birdnet-team/birdnet-analyzer
- Repository: https://github.com/birdnet-team/birdnet-analyzer

## Overview

##### Project Type and Purpose
- BirdNET-Analyzer is a Python-based, open-source acoustic analysis tool.
- It offers both command-line (CLI) and graphical (GUI) interfaces for running deep-learning inference on audio, plus modules for segmentation, search, embeddings, evaluation, and training.

##### File Structure to Derive Components
- Top‐level Package: `birdnet_analyzer/` – the Python package housing all functionality.
- User Interfaces:
- `cli.py` and subfolders (`analyze/cli.py`, `search/cli.py`, etc.)
- `gui/` – HTML, CSS, JS assets plus Python wrappers.
- Core Processing Engines (for each domain):
- `analyze/core.py`
- `segments/core.py`
- `search/core.py`
- `embeddings/core.py`
- `evaluation/assessment/...` and `evaluation/preprocessing/...`
- `train/core.py`
- Model & Configuration:
- `model.py` – loads the neural net
- `config.py` – central config management
- `eBird_taxonomy_codes_2024E.json` – taxonomy data
- `labels/` – multilingual label files
- Networking:
- `network/server.py` & `network/client.py` – optional remote-processing API.
- Utilities & Shared Logic:
- `utils.py` and `*/utils.py` in each submodule.
- Packaging & Deployment:
- `Dockerfile` and `.github/workflows/docker-build.yml`
- `pyproject.toml` – build config.
- Tests: `tests/` to validate each module.

##### README for Additional Insights
- Confirms dual‐interface (CLI + GUI), Docker support, and that models are fetched from Zenodo.
- Emphasizes extensibility for single files vs. bulk datasets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Container
    subgraph "Docker Container" 
        direction TB
        %% BirdNET Analyzer Package
        subgraph "birdnet_analyzer package"
            direction TB

            %% User Layer
            subgraph "User Layer"
                direction TB
                CLI["CLI Interface"]:::frontend
                GUI["GUI Interface"]:::frontend
            end

            %% Application Layer
            subgraph "Application Layer"
                direction TB
                subgraph "Core Engines"
                    direction TB
                    AnalyzeCore["Analyze Engine"]:::core
                    SegmentsCore["Segments Engine"]:::core
                    SearchCore["Search Engine"]:::core
                    EmbeddingsCore["Embeddings Engine"]:::core
                    EvaluationCore["Evaluation Engine"]:::core
                    TrainingCore["Training Engine"]:::core
                end
                ModelLoader["Model Loader"]:::core
                ConfigManager["Config Manager"]:::core
                subgraph Networking
                    direction TB
                    NetServer["Network Server"]:::network
                    NetClient["Network Client"]:::network
                end
            end

            %% Data Layer
            subgraph "Data Layer"
                direction TB
                AudioIO["Audio I/O"]:::data
                TaxonomyJSON["Taxonomy JSON"]:::data
                LabelsDir["Labels Directory"]:::data
                Results["Results (CSV, Plots)"]:::data
            end

            %% Utilities
            Utils["Shared Utils"]:::util

        end
    end

    %% External Systems
    Zenodo["Model Repository (Zenodo)"]:::external
    eBird["eBird Taxonomy Updates"]:::external

    %% Connections
    CLI -->|runs| AnalyzeCore
    CLI -->|runs| SegmentsCore
    CLI -->|runs| SearchCore
    CLI -->|runs| EmbeddingsCore
    CLI -->|runs| EvaluationCore
    CLI -->|runs| TrainingCore

    GUI -->|invokes| AnalyzeCore
    GUI -->|invokes| SegmentsCore
    GUI -->|invokes| SearchCore
    GUI -->|invokes| EmbeddingsCore
    GUI -->|invokes| EvaluationCore
    GUI -->|invokes| TrainingCore

    AnalyzeCore -->|loads model| ModelLoader
    SegmentsCore -->|loads model| ModelLoader
    SearchCore -->|loads model| ModelLoader
    EmbeddingsCore -->|loads model| ModelLoader
    TrainingCore -->|loads model| ModelLoader

    AnalyzeCore -->|reads| AudioIO
    SegmentsCore -->|reads| AudioIO
    SearchCore -->|reads| AudioIO

    EvaluateCore -->|writes| Results
    AnalyzeCore -->|writes| Results
    TrainingCore -->|writes| Results

    ModelLoader -->|fetches from| Zenodo
    ConfigManager -->|provides config| AnalyzeCore
    ConfigManager -->|provides config| SegmentsCore
    ConfigManager -->|provides config| SearchCore
    ConfigManager -->|provides config| EmbeddingsCore
    ConfigManager -->|provides config| EvaluationCore
    ConfigManager -->|provides config| TrainingCore

    NetClient <-->|RPC| NetServer
    NetServer -->|forwards| AnalyzeCore
    NetServer -->|forwards| SegmentsCore
    NetServer -->|forwards| SearchCore
    NetServer -->|forwards| EmbeddingsCore
    NetServer -->|forwards| EvaluationCore
    NetServer -->|forwards| TrainingCore

    eBird -->|updates| TaxonomyJSON

    Utils -->|shared| AnalyzeCore
    Utils -->|shared| SegmentsCore
    Utils -->|shared| SearchCore
    Utils -->|shared| EmbeddingsCore
    Utils -->|shared| EvaluationCore
    Utils -->|shared| TrainingCore

    %% Click Events
    click CLI "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/cli.py"
    click AnalyzeCore "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/analyze/core.py"
    click SegmentsCore "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/segments/core.py"
    click SearchCore "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/search/core.py"
    click EmbeddingsCore "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/embeddings/core.py"
    click TrainingCore "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/train/core.py"
    click ModelLoader "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/model.py"
    click ConfigManager "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/config.py"
    click NetServer "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/network/server.py"
    click NetClient "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/network/client.py"
    click Utils "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/utils.py"
    click CLI "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/cli.py"
    click GUI "https://github.com/birdnet-team/birdnet-analyzer/tree/main/birdnet_analyzer/gui/"
    click AudioIO "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/example/soundscape.wav"
    click TaxonomyJSON "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/eBird_taxonomy_codes_2024E.json"
    click LabelsDir "https://github.com/birdnet-team/birdnet-analyzer/tree/main/birdnet_analyzer/labels/"
    click Zenodo "https://github.com/birdnet-team/birdnet-analyzer/blob/main/birdnet_analyzer/.github/workflows/docker-build.yml"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1F618D,color:#1F618D
    classDef core fill:#D5F5E3,stroke:#27AE60,color:#27AE60
    classDef data fill:#FCF3CF,stroke:#F1C40F,color:#B9770E
    classDef external fill:#ECECEC,stroke:#7B7D7D,color:#566573
    classDef network fill:#FDEDEC,stroke:#C0392B,color:#922B21
    classDef util fill:#E8DAEF,stroke:#8E44AD,color:#633974
```
