Architecture

BirdNet-Behavior is a single binary built from eight Rust workspace crates, each with a clear responsibility:

birdnet-behavior (single binary)
├── birdnet-core          Audio capture, decode, resample, mel spectrogram, ML inference
├── birdnet-db            SQLite (OLTP) + DuckDB (OLAP), migrations, resilience, backup
├── birdnet-web           axum web server, REST API, WebSocket, HTMX templates
├── birdnet-integrations  BirdWeather, Apprise, email, Wikipedia images, MQTT, auto-update
├── birdnet-behavioral    DuckDB behavioral analytics (built in; on by default)
├── birdnet-timeseries    Activity, diversity, trend, peak, gap, session analytics
├── birdnet-migrate       BirdNET-Pi schema detection, validation, import
└── birdnet-scheduler     Solar calculations, recording-window scheduling

Design principles

• One self-contained binary — the ONNX Runtime and DuckDB analytics engine are compiled in; no Python, no virtualenv. Deploy by copying a file (it links the host’s system glibc, ≥ 2.39).
• Synchronous, unsafe-free library crates — birdnet-core and birdnet-db are blocking; async (Tokio) lives only in the application layer. Blocking work runs on tokio::task::spawn_blocking.
• Hand-rolled error types in libraries (no anyhow/thiserror), with unsafe forbidden workspace-wide (unsafe_code = "forbid"), missing_docs enforced, and Clippy pedantic + nursery denied in CI.

Deep-dive design documents

The complete set of 16 design documents lives in the repository under docs/architecture/; the most relevant:

The index lives at docs/RUST_ARCHITECTURE_PLAN.md.