Vogelring 🦆

A comprehensive bird tracking and sighting management system for ornithologists and bird watchers. Vogelring enables researchers to track ringed birds, manage sightings, analyze migration patterns, and maintain detailed records of bird populations.

Features

Core Functionality

• Bird Sighting Management: Record, edit, and track bird sightings with detailed metadata
• Ring Database: Comprehensive database of ringed birds with identification and tracking
• Interactive Maps: Visualize sightings on interactive maps with location accuracy indicators
• Advanced Search: Powerful search functionality with partial ring reading support (wildcards)
• Family Trees: Track breeding relationships and family lineages between birds

Analytics & Insights

• Friend Analysis: Discover which birds are frequently seen together
• Seasonal Patterns: Analyze seasonal migration and behavior patterns
• Dashboard: Real-time statistics and insights about bird populations
• Data Quality: Built-in data validation and quality assessment tools
• Radius Analysis: Find all sightings within a specified geographic radius

Data Management

• Import/Export: Support for various data formats and migration tools
• Ringing Records: Manage detailed ringing information and metadata
• Reporting: Generate shareable reports with customizable time ranges

Getting Started

./dev.sh

This single command:

• Creates .env from template (if missing)
• Installs frontend dependencies and builds
• Starts PostgreSQL, API, and Nginx via Docker

Access: http://localhost (API at port 8000)

Useful commands:

docker-compose logs -f    # View logs
docker-compose down       # Stop services
docker-compose down -v    # Stop and remove data

Frontend Development (Hot Reload)

For active frontend work:

# Terminal 1: Backend only
docker-compose up postgres api

# Terminal 2: Frontend dev server
cd frontend && npm run dev

Frontend dev server runs at http://localhost:5173 with hot reload.

Architecture

• Frontend: Vue.js 3 with TypeScript and Vuetify for Material Design components
• Backend: FastAPI application with PostgreSQL database
• Infrastructure: Docker Compose orchestration
• Maps: Leaflet for interactive mapping
• Charts: ECharts for data visualization

Development

Backend Development

The FastAPI backend is located in the backend/ directory:

backend/
├── src/
│   ├── main.py              # FastAPI application entry point
│   ├── database/
│   │   ├── connection.py    # Database connection and session management
│   │   └── models.py        # SQLAlchemy ORM models
│   └── api/
│       └── routers/         # API route handlers
├── Dockerfile
└── pyproject.toml

Database Schema

The application uses PostgreSQL with three main tables:

• ringings: Bird ringing data
• sightings: Bird sighting observations
• family_tree_entries: Family relationship data

Services

• postgres: PostgreSQL 15 database with persistent volumes
• api: FastAPI backend application
• nginx: Reverse proxy and static file server

Data Model

Core Entities

• Sightings: Individual bird observations with location, date, and metadata
• Birds: Unique ringed birds with identification and tracking information
• Ringing: Detailed ringing records including location, date, and ringer information
• Family Trees: Breeding relationships and lineage tracking

Key Features

• Flexible Data Entry: Support for partial readings and uncertain identifications
• Geographic Precision: Exact and approximate location tracking
• Temporal Analysis: Date-based filtering and seasonal pattern analysis
• Relationship Mapping: Partner and offspring relationship tracking

API Documentation

The API provides comprehensive endpoints for:

• Sightings: CRUD operations, filtering, and search
• Birds: Metadata retrieval and suggestions
• Analytics: Friend analysis, seasonal patterns, radius searches
• Ringing: Ringing record management
• Family: Family tree and relationship management

Deployment

For production deployment:

1. System requirements:

   • Docker and Docker Compose installed
   • Sufficient storage for database and logs

2. Configuration:

   • Update .env with production values
   • Set up backup procedures for PostgreSQL data

3. Monitoring:

   • All services include health checks
   • Logs available via docker-compose logs

Contact

For questions or to become a user, please contact: anton@antonroesler.com