# FlockWatch Bird Survey

FlockWatch is a citizen-science platform for collecting, validating, and exporting bird observation data from community surveys. It supports point counts, transect walks, incidental sightings, offline field entry, and structured exports for researchers, conservation groups, and local bird clubs.

## Overview

The project helps volunteers record bird observations in a consistent format while giving coordinators tools to manage survey sites, review submitted records, and export cleaned datasets for analysis.

Typical use cases include:

- Seasonal breeding bird surveys
- Migration counts
- Urban biodiversity monitoring
- Wetland or park inventory projects
- Community science programs run by schools, NGOs, or municipalities

## Features

- Create and manage survey sites, routes, and observation points
- Record species, count, behavior, distance band, habitat, and notes
- Capture date, time, GPS location, observer name, and weather conditions
- Support for offline-friendly CSV imports from field sheets
- Species checklist validation using a configurable taxonomy file
- Duplicate and outlier detection for coordinator review
- Export observations as CSV or GeoJSON
- Role-based workflow for volunteers, reviewers, and administrators
- Configurable survey protocols and required fields

## Install

### Requirements

- Python 3.11+
- PostgreSQL 14+
- Node.js 20+ if running the web interface
- Git

### Backend

```bash
git clone https://github.com/example/flockwatch.git
cd flockwatch

python -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py createsuperuser
```

### Frontend

```bash
cd web
npm install
npm run build
```

### Development Server

From the project root:

```bash
python manage.py runserver
```

Then open:

```text
http://localhost:8000
```

## Usage

### Create a Survey Project

Log in as an administrator and create a new project with:

- Project name
- Survey season
- Target region
- Default protocol
- Coordinator contact details

### Add Survey Sites

Sites can be added manually through the web interface or imported from CSV:

```bash
python manage.py import_sites data/sites.csv
```

Expected columns:

```csv
site_code,name,latitude,longitude,habitat_type,access_notes
```

### Submit Observations

Volunteers can submit observations through the web form or upload a CSV field sheet:

```bash
python manage.py import_observations data/june-counts.csv --project spring-2026
```

Expected observation fields include:

```csv
site_code,observer,date,start_time,species_code,count,behavior,distance_band,notes
```

### Review Records

Coordinators can review flagged records from the admin dashboard. Records may be flagged for:

- Rare species in the project region
- Counts above configured thresholds
- Missing required fields
- Coordinates outside the assigned survey site
- Duplicate submissions

### Export Data

Export reviewed records as CSV:

```bash
python manage.py export_observations --project spring-2026 --format csv > observations.csv
```

Export reviewed records as GeoJSON:

```bash
python manage.py export_observations --project spring-2026 --format geojson > observations.geojson
```

## Configuration

Configuration is handled through environment variables and project-level settings.

### Environment Variables

Create a `.env` file from the example template:

```bash
cp .env.example .env
```

Common settings:

```env
DATABASE_URL=postgres://flockwatch:flockwatch@localhost:5432/flockwatch
SECRET_KEY=change-this-in-production
DEBUG=false
ALLOWED_HOSTS=localhost,127.0.0.1
DEFAULT_TIMEZONE=America/Toronto
MEDIA_ROOT=./media
EXPORT_REVIEWED_ONLY=true
```

### Species Checklist

The default species checklist is loaded from:

```text
config/species_checklist.csv
```

Expected columns:

```csv
species_code,common_name,scientific_name,taxonomic_order,regional_status
```

### Survey Protocols

Survey protocols are defined in:

```text
config/protocols.yml
```

Example:

```yaml
point_count:
  duration_minutes: 10
  require_weather: true
  require_distance_band: true
  allowed_distance_bands:
    - 0-25m
    - 25-50m
    - 50-100m
    - >100m

transect:
  require_start_location: true
  require_end_location: true
  require_distance_band: false
```

### Review Rules

Outlier and validation rules are configured in:

```text
config/review_rules.yml
```

Example:

```yaml
rare_species_requires_review: true
high_count_thresholds:
  AMRO: 50
  BCCH: 40
  CANG: 200
duplicate_window_minutes: 30
max_site_distance_meters: 250
```

## License

This project is released under the MIT License.