BirdNET-NG Feature Roadmap

Phase 1 — Core Loop (MVP) ✅

The minimum viable distributed bird identification system.

P1.1 — Satellite Audio Capture ✅

✓ Audio capture from USB/I2S microphone via ALSA (arecord)
✓ 3-second chunking with configurable overlap
✓ WAV encoding at 48kHz mono (BirdNET native sample rate)
✓ Local disk storage (write-before-send)
✓ SQLite outbox queue (sql.js, persisted to disk)
✓ Simulated capture mode (sine wave) for development
✓ Replay capture mode (real bird audio from WAV files) for testing

P1.2 — Satellite → Hub Transport ✅

✓ MQTT client with auto-reconnect
✓ Base64 audio payload with JSON metadata envelope
✓ Outbox drain loop with exponential backoff
✓ Hub-side acknowledgment (chunk marked acked only after storage confirmed)
✓ Configurable retention policy for local cleanup

P1.3 — Hub Audio Ingestion ✅

✓ MQTT subscriber receiving audio chunks
✓ Store audio blobs in MinIO (keyed by {tenant_id}/{satellite_id}/{chunk_id}.wav)
✓ Insert audio_chunks record in PostgreSQL
✓ Enqueue processing job in BullMQ

P1.4 — Inference Worker ✅

✓ BullMQ consumer pulling audio processing jobs (async Python worker)
✓ Download audio from MinIO
✓ Run BirdNET TFLite model (via birdnetlib, tflite-runtime 2.14)
✓ Write detection results to PostgreSQL
✓ Basic species identification with confidence scores
✓ Geo-aware species filtering (location + date)

P1.5 — Web UI ✅

✓ Dashboard: satellite status cards, recent detections, species count
✓ Detection list with filtering (satellite, min confidence slider)
✓ Audio playback for detections
✓ Satellite fleet cards (status, location, CPU temp, storage, battery, uptime)
✓ Tenant selector with "All Tenants" option
✓ Dark theme, responsive layout
✓ Spectrogram visualization (Cooley-Tukey FFT, Viridis colormap, 0–12kHz)

P1.6 — Multi-Tenancy Foundation ✅

✓ Tenant registration and management
✓ API key generation scoped to tenant (viewer, member, admin, satellite roles)
✓ Row-level tenant isolation on all queries
✓ Tenant-scoped MinIO paths
✓ API key authentication middleware with role-based guards
✓ Tenant scoping enforcement (scoped keys cannot access other tenants)
✓ Internal API key for web frontend (cross-tenant admin)

P1.7 — Deployment ✅

✓ Docker Compose for full 7-container hub stack
✓ Traefik integration (HTTPS + MQTTS TLS termination)
✓ Three FQDNs (web, MQTT, MinIO console)
✓ All configuration via .env environment variables
✓ Persistent storage via bind mounts
✓ Satellite install script for Raspberry Pi

Phase 2 — Intelligence

Smart features that improve detection quality and user experience.

P2.1 — Geo-Aware Inference ✅

✓ Satellite GPS coordinate reporting
✓ Live GPS via gpsd for Pi satellites
✓ Species range filtering based on location + month
✓ BirdNET location filter integration in inference worker
✓ Reduced candidate list → faster and more accurate inference

P2.2 — Rare Species Alerts ✅

✓ Frequency-based rarity model (first sighting + low frequency detection)
✓ Real-time alert generation on unusual detections
✓ WebSocket push to connected UI clients (toast notifications)
✓ Webhook support (Slack, custom URL)
✓ Per-tenant custom watchlists (tenant settings, watchlist_species array)

P2.3 — Confidence-Based Re-Processing ✅

✓ Configurable "uncertain" confidence band (default: 0.4–0.7)
✓ Auto-requeue uncertain detections with lower threshold (0.05)
✓ Second pass updates confidence with GREATEST(old, new)
✓ Flag for human verification if still uncertain (pending_review)

P2.4 — Satellite Health & Telemetry ✅

✓ Periodic telemetry reports from satellites (battery, storage, CPU, network)
✓ Fleet dashboard in web UI (satellite cards with telemetry)
✓ Satellite offline detection with configurable timeout
✓ Alerts: offline, low storage, overheating, high packet loss

P2.5 — User Authentication & Authorization ✅

✓ Email/password registration with bcrypt password hashing
✓ JWT cookie-based sessions (httpOnly, secure, 7-day expiry)
✓ Login and registration pages with form validation
✓ Auth-gated routing (unauthenticated users see only login/register)
✓ Auto-login after registration
✓ Logout with cookie clearing
✓ /api/auth/me endpoint returns current user + tenant memberships
✓ Blocked user detection at login time

P2.6 — Multi-Tenant Membership ✅

✓ Users are global (no tenant_id on users table)
✓ Multi-tenant membership via tenant_members join table
✓ Per-tenant roles: viewer, member, admin, owner
✓ Tenant selector in sidebar for users with multiple memberships
✓ Platform admin with cross-tenant access (via DB flag or env var)
✓ Platform admin hidden from tenant member lists
✓ Self-service tenant creation (gated by platform setting)

P2.7 — Invite System ✅

✓ Admin-generated single-use invite links
✓ Invite scoped to tenant + role (viewer, member, admin)
✓ 72-hour default expiry (configurable per invite)
✓ Registration via invite bypasses self-registration setting
✓ Invite link displayed with copy-to-clipboard
✓ Pending invite list with revoke capability
✓ Invite validation before user creation (no orphan accounts)

P2.8 — Admin Page ✅

✓ Platform tab: global user management table with search
✓ Platform tab: block/unblock users
✓ Platform tab: delete users with modal confirmation
✓ Platform tab: reset password with modal dialog
✓ Platform tab: platform admin accounts shown as read-only
✓ Platform tab: platform admin self-service password change
✓ Tenants tab: member list with role display
✓ Tenants tab: role change via dropdown (viewer/member/admin)
✓ Tenants tab: remove member with modal confirmation
✓ Tenants tab: invite link generation with role selection
✓ Tenants tab: pending invites list with revoke
✓ Tenants tab: tenant selector for multi-tenant admins

P2.9 — Settings Page ✅

✓ Tenant settings: confidence thresholds (high, low, minimum) with sliders
✓ Tenant settings: offline timeout (minutes)
✓ Tenant settings: verification consensus (votes needed)
✓ Tenant settings: satellite retention (hours)
✓ Platform settings: self-registration toggle
✓ Platform settings: tenant creation toggle
✓ Platform settings: invite links toggle
✓ Settings API: /api/settings/tenant (GET/PUT)
✓ Settings API: /api/settings/platform (GET/PUT)

P2.10 — UI Enhancements ✅

✓ WebSocket connection status indicator (Live / Reconnecting...)
✓ Toast notifications for action feedback (success and error)
✓ Modal confirmations for all destructive actions
✓ User menu in sidebar (name, email, platform admin badge, sign out)

P2.11 — On-Device Audio Pre-Filtering ✅

✓ RMS silence rejection on satellite and mobile
✓ Bird-band frequency check (reject audio outside bird frequency range)
✓ Reduces unnecessary uploads and processing

P2.12 — Custom Watchlists for Species Alerts ✅

✓ Per-tenant watchlist_species array in tenant settings
✓ Alerts triggered when watchlisted species are detected

P2.13 — Web Container Auth Refactor ✅

✓ nginx no longer injects HUB_INTERNAL_API_KEY on API requests
✓ All user auth flows through JWT cookies (set by login, forwarded by browser)
✓ Internal API key retained for backwards-compatible machine access only

Phase 3 — Community

Features that enable collaboration and data sharing.

P3.1 — Collaborative Verification ✅

✓ Backend voting endpoint (confirm / reject / unsure)
✓ Configurable consensus threshold (default: 3, adjustable in tenant settings)
✓ Verification review queue in web UI (card-based with spectrogram + audio)
✓ Keyboard shortcuts (1=Yes, 2=No, 3=Unsure, arrows=navigate)
✓ Auto-advance to next unvoted detection
✓ Progress bar and vote tracking
✓ Verification statistics and user leaderboard

P3.2 — Scheduled Recording Profiles ✅

✓ Profile definitions (dawn_chorus, night_migration, low_power, continuous)
✓ Sunrise/sunset calculation from GPS coordinates (NOAA solar algorithm)
✓ Recording scheduler pauses capture outside active windows
✓ Hub → satellite profile push via MQTT
✓ Per-satellite profile assignment in web UI
✓ Schedule preview on satellite cards (resolved sun times + windows)
✓ Schedule display in mobile app (read-only)
✓ Night migration uses sunset-relative times (adapts to season)

P3.3 — Data Federation & Export (partial)

✓ CSV/JSON export of detections (filterable, downloadable from UI)
✓ eBird checklist generation
✓ xeno-canto recording submission
✓ iNaturalist observation export
Scheduled automatic exports

P3.4 — Multi-Language Bird Names ✅

✓ Species translation service (38 languages, loaded from BirdNET label files)
✓ SpeciesName component with SpeciesI18nProvider context
✓ User preferences for primary and secondary display languages

P3.5 — Multi-Hub Workers (partial)

✓ Worker registration and heartbeat
[~] Contributed worker onboarding (partial: worker dashboard shows connected workers)
✓ Worker performance metrics (avg processing time, queue stats)
✓ Worker dashboard in web UI
GPU vs CPU worker differentiation

Phase 4 — Scale & Polish

P4.1 — Phone App ✅

✓ Cross-platform mobile app (Capacitor)
✓ Android phone satellite app with in-app registration, telemetry, GPS
✓ Native AudioRecord plugin for Android
✓ Background mode for continuous recording
✓ In-app log viewer
✓ Pause/resume recording
✓ GPS gate: requires location before recording (auto or manual)
✓ GPS auto-update toggle with configurable interval (30s–10min)
✓ Keep screen on toggle
✓ Settings panel: rename satellite, manage GPS, unregister with confirmation
✓ Heartbeat keepalive (30s, QoS 1)
✓ Schedule display (read-only, from hub)
✓ Storage telemetry via Storage API
[~] Push notifications for rare species (WebSocket toasts implemented, no native push yet)

P4.2 — Analytics Page ✅

✓ Detection trends over time (daily trend chart)
✓ Hourly species activity chart
✓ Top species summary

P4.3 — User Preferences ✅

✓ Per-user language settings (primary_language, secondary_languages on users table)
✓ User preferences API (PUT /api/auth/me/preferences)
✓ UserPreferences page in web UI

P4.4 — Species Images ✅

✓ Bird thumbnails from Wikipedia (Wikimedia Commons API)
✓ Background download queue (configurable delay between fetches)
✓ Permanent storage in MinIO (no TTL expiry)
✓ Proxy endpoint serves from MinIO (Wikipedia never hit at request time)
✓ Placeholder display while downloading (pulsing indicator)
✓ Lightbox with full-size image + Wikipedia link
✓ Platform admin cache management (stats, retry failed, clear)

P4.5 — MQTT Heartbeat ✅

✓ Lightweight keepalive every 30 seconds (QoS 1)
✓ Decouples online status from audio chunk sending
✓ Heartbeat state visible on satellite cards (Recording, Paused, Scheduled off)
✓ Telemetry upgraded from QoS 0 to QoS 1 for reliability

P4.6 — Responsive Web UI ✅

✓ Hamburger menu on mobile (< 768px)
✓ Sidebar slides in as overlay with backdrop
✓ Single-column card grids on mobile
✓ Scrollable tables
✓ Stacked filters

P4.7 — Versioning & Documentation ✅

✓ Unified version across all packages (version-bump script)
✓ VitePress documentation site with version switcher
✓ CHANGELOG.md with structured release notes
✓ Release protocol documented
✓ Design system documented (buttons, badges, color palette)

P4.8 — Species Catalog & Detection Map ✅

✓ Species catalog page with sortable cards and rich stats
✓ Per-species: detection count, confidence, first/last seen, satellite count
✓ Sort: most detected, most recent, alphabetical, confidence, rarest, most satellites
✓ Detection map with Leaflet.js + OpenStreetMap
✓ Satellite markers colored by status, sized by detection count
✓ Popup with detection stats and top 5 species

P4.9 — Account & User Management ✅

✓ Account page: edit name, email, change password, language preferences
✓ Account self-deletion with confirmation (blocks sole tenant owners)
✓ Login rate limiting (20 attempts/IP/15min)
✓ Account lockout after 5 failed attempts (15min)
✓ Last login tracking (timestamp + IP)
✓ Audit log: all admin and user actions recorded
✓ Audit Log page for platform admins (paginated, color-coded)
✓ Tenant ownership transfer
✓ User search filters (status, tenant)
✓ Platform admin auto-persisted from PLATFORM_ADMIN_EMAILS env var
✓ Auth resolves live user data from DB (not stale JWT)

P4.10 — Design System ✅

✓ Unified CSS classes for all buttons (btn-primary, btn-secondary, btn-danger, btn-ghost)
✓ Button sizes: btn-sm (tables), default (modals), btn-lg (forms)
✓ Hover, disabled, active states in CSS (no inline JS)
✓ Unified badge classes (online, offline, degraded, muted, accent, rare, danger)
✓ Responsive layout with mobile hamburger menu
✓ Version display in sidebar

P4.12 — Advanced Analytics (remaining)

Migration pattern visualization across satellite network
Biodiversity indices per location

P4.13 — Model Management

Support multiple BirdNET model versions
A/B testing of model versions
Custom fine-tuned model deployment
Model performance comparison dashboards