# tphakala/birdnet-go architecture

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

- Interactive diagram: https://gitdiagram.com/tphakala/birdnet-go
- Repository: https://github.com/tphakala/birdnet-go

## Overview

BirdNET-Go is a self-hosted, real-time wildlife sound analyzer. Audio sources feed capture and analysis, where installed classifiers produce detections that are stored, exposed in the web interface, and evaluated for alerts. The interface also supports configuration, analytics, imports, and system operations. README statements establish the product workflow and major capabilities; source excerpts show selected audio, model, alerting, storage, and server responsibilities. Several UI and integration relationships are documented but their implementation was not sampled.

Main entry points: [`internal/analysis/audio_pipeline_service.go`](https://github.com/tphakala/birdnet-go/blob/main/internal/analysis/audio_pipeline_service.go) (Analysis pipeline), [`frontend/src/App.svelte`](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/App.svelte) (Web application), [`internal/audiocore/engine/engine.go`](https://github.com/tphakala/birdnet-go/blob/main/internal/audiocore/engine/engine.go) (Audio engine), [`internal/classifier/model_manager.go`](https://github.com/tphakala/birdnet-go/blob/main/internal/classifier/model_manager.go) (Model manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audio["Audio and detection"]
  node_audio_engine["Audio engine<br/>[engine.go]"]
  node_stream_pipeline["Stream pipeline<br/>[pipeline.go]"]
  node_analysis["Analysis pipeline"]
end

subgraph group_data["Data and models"]
  node_model_manager["Model manager<br/>[model_manager.go]"]
  node_detections[("Detection storage<br/>[manager.go]")]
  node_species_index["Species lookup<br/>[service.go]"]
end

subgraph group_web["Web experience"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_frontend["Web application<br/>[App.svelte]"]
  node_dashboard["Dashboard"]
  node_analytics["Analytics pages<br/>[Species.svelte]"]
  node_live_audio["Live audio view"]
  node_settings["Settings interface<br/>[settings.ts]"]
end

subgraph group_ops["Operations and integrations"]
  node_app_lifecycle["Application lifecycle<br/>[app.go]"]
  node_config["Configuration<br/>[storage.go]"]
  node_alert_engine["Alert rules<br/>[engine.go]"]
  node_mqtt["MQTT integration<br/>[client.go]"]
  node_birdweather["BirdWeather"]
  node_support["Support diagnostics"]
end

node_operator(("Operator"))
node_audio_sources(("Audio sources"))
node_external_targets(("Alert destinations"))

node_operator -->|"uses"| node_frontend
node_audio_sources -->|"provide audio"| node_audio_engine
node_audio_engine -->|"streams frames"| node_stream_pipeline
node_audio_engine -->|"feeds analysis"| node_analysis
node_analysis -->|"uses classifiers"| node_model_manager
node_model_manager -->|"classifies audio"| node_analysis
node_analysis -->|"stores detections"| node_detections
node_analysis -.->|"looks up species"| node_species_index
node_detections -->|"serves detection data"| node_http_server
node_http_server -->|"serves app and API"| node_frontend
node_frontend -->|"renders"| node_dashboard
node_frontend -->|"routes to"| node_analytics
node_frontend -->|"routes to"| node_live_audio
node_operator -->|"configures"| node_settings
node_settings -.->|"updates settings"| node_config
node_analysis -->|"emits detection events"| node_alert_engine
node_alert_engine -->|"dispatches alerts"| node_external_targets
node_analysis -.->|"publishes events"| node_mqtt
node_analysis -.->|"sends detections"| node_birdweather
node_operator -->|"requests diagnostics"| node_support
node_app_lifecycle -.->|"starts with settings"| node_config

click node_app_lifecycle "https://github.com/tphakala/birdnet-go/blob/main/internal/app/app.go"
click node_config "https://github.com/tphakala/birdnet-go/blob/main/internal/conf/storage.go"
click node_audio_engine "https://github.com/tphakala/birdnet-go/blob/main/internal/audiocore/engine/engine.go"
click node_stream_pipeline "https://github.com/tphakala/birdnet-go/blob/main/internal/audiocore/stream/pipeline.go"
click node_analysis "https://github.com/tphakala/birdnet-go/blob/main/internal/analysis/audio_pipeline_service.go"
click node_model_manager "https://github.com/tphakala/birdnet-go/blob/main/internal/classifier/model_manager.go"
click node_detections "https://github.com/tphakala/birdnet-go/blob/main/internal/datastore/v2/manager.go"
click node_species_index "https://github.com/tphakala/birdnet-go/blob/main/internal/speciesindex/service.go"
click node_http_server "https://github.com/tphakala/birdnet-go/blob/main/internal/api/server.go"
click node_frontend "https://github.com/tphakala/birdnet-go/blob/main/frontend/src/App.svelte"
click node_dashboard "https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/dashboard/pages/DashboardPage.svelte"
click node_analytics "https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/analytics/pages/Species.svelte"
click node_live_audio "https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/live-stream/pages/LiveStreamPage.svelte"
click node_settings "https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/stores/settings.ts"
click node_alert_engine "https://github.com/tphakala/birdnet-go/blob/main/internal/alerting/engine.go"
click node_mqtt "https://github.com/tphakala/birdnet-go/blob/main/internal/mqtt/client.go"
click node_birdweather "https://github.com/tphakala/birdnet-go/blob/main/internal/birdweather/birdweather_client.go"
click node_support "https://github.com/tphakala/birdnet-go/blob/main/internal/support/database_collector.go"

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_audio_engine,node_stream_pipeline,node_analysis toneBlue
class node_model_manager,node_detections,node_species_index toneAmber
class node_http_server,node_frontend,node_dashboard,node_analytics,node_live_audio,node_settings toneMint
class node_app_lifecycle,node_config,node_alert_engine,node_mqtt,node_birdweather,node_support toneRose
class node_operator,node_audio_sources,node_external_targets toneIndigo
```

## Components

### Audio and detection

- [Audio engine](https://github.com/tphakala/birdnet-go/blob/main/internal/audiocore/engine/engine.go): `internal/audiocore/engine/engine.go`
- [Stream pipeline](https://github.com/tphakala/birdnet-go/blob/main/internal/audiocore/stream/pipeline.go): `internal/audiocore/stream/pipeline.go`
- [Analysis pipeline](https://github.com/tphakala/birdnet-go/blob/main/internal/analysis/audio_pipeline_service.go): `internal/analysis/audio_pipeline_service.go`

### Data and models

- [Model manager](https://github.com/tphakala/birdnet-go/blob/main/internal/classifier/model_manager.go): `internal/classifier/model_manager.go`
- [Detection storage](https://github.com/tphakala/birdnet-go/blob/main/internal/datastore/v2/manager.go): `internal/datastore/v2/manager.go`
- [Species lookup](https://github.com/tphakala/birdnet-go/blob/main/internal/speciesindex/service.go): `internal/speciesindex/service.go`

### Web experience

- [HTTP server](https://github.com/tphakala/birdnet-go/blob/main/internal/api/server.go): `internal/api/server.go`
- [Web application](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/App.svelte): `frontend/src/App.svelte`
- [Dashboard](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/dashboard/pages/DashboardPage.svelte): `frontend/src/lib/desktop/features/dashboard/pages/DashboardPage.svelte`
- [Analytics pages](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/analytics/pages/Species.svelte): `frontend/src/lib/desktop/features/analytics/pages/Species.svelte`
- [Live audio view](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/desktop/features/live-stream/pages/LiveStreamPage.svelte): `frontend/src/lib/desktop/features/live-stream/pages/LiveStreamPage.svelte`
- [Settings interface](https://github.com/tphakala/birdnet-go/blob/main/frontend/src/lib/stores/settings.ts): `frontend/src/lib/stores/settings.ts`

### Operations and integrations

- [Application lifecycle](https://github.com/tphakala/birdnet-go/blob/main/internal/app/app.go): `internal/app/app.go`
- [Configuration](https://github.com/tphakala/birdnet-go/blob/main/internal/conf/storage.go): `internal/conf/storage.go`
- [Alert rules](https://github.com/tphakala/birdnet-go/blob/main/internal/alerting/engine.go): `internal/alerting/engine.go`
- [MQTT integration](https://github.com/tphakala/birdnet-go/blob/main/internal/mqtt/client.go): `internal/mqtt/client.go`
- [BirdWeather](https://github.com/tphakala/birdnet-go/blob/main/internal/birdweather/birdweather_client.go): `internal/birdweather/birdweather_client.go`
- [Support diagnostics](https://github.com/tphakala/birdnet-go/blob/main/internal/support/database_collector.go): `internal/support/database_collector.go`

### Other components

- **Operator**
- **Audio sources**
- **Alert destinations**

## Connections

- Operator → Web application: uses
- Audio sources → Audio engine: provide audio
- Audio engine → Stream pipeline: streams frames (evidence: `internal/audiocore/engine/engine.go`)
- Audio engine → Analysis pipeline: feeds analysis
- Analysis pipeline → Model manager: uses classifiers (evidence: `internal/analysis/audio_pipeline_service.go`)
- Model manager → Analysis pipeline: classifies audio
- Analysis pipeline → Detection storage: stores detections
- Analysis pipeline → Species lookup: looks up species
- Detection storage → HTTP server: serves detection data
- HTTP server → Web application: serves app and API (evidence: `internal/api/server.go`)
- Web application → Dashboard: renders (evidence: `frontend/src/App.svelte`)
- Web application → Analytics pages: routes to (evidence: `frontend/src/App.svelte`)
- Web application → Live audio view: routes to (evidence: `frontend/src/App.svelte`)
- Operator → Settings interface: configures
- Settings interface → Configuration: updates settings
- Analysis pipeline → Alert rules: emits detection events (evidence: `internal/analysis/audio_pipeline_service.go`)
- Alert rules → Alert destinations: dispatches alerts
- Analysis pipeline → MQTT integration: publishes events
- Analysis pipeline → BirdWeather: sends detections
- Operator → Support diagnostics: requests diagnostics
- Application lifecycle → Configuration: starts with settings
