# FieldFlock Bird Survey

FieldFlock is a lightweight citizen-science platform for collecting, validating, and exporting local bird survey observations. It is designed for community monitoring programs, park associations, classrooms, and volunteer survey teams that need a simple way to record species, counts, effort, location, weather, and observer notes.

## Features

- Create standardized bird survey checklists by site, route, or point count station
- Record species, counts, breeding evidence, behavior, and optional confidence notes
- Track survey effort including start time, duration, distance, observer count, and weather
- Support offline-first field entry with later sync
- Flag unusual species, high counts, and incomplete effort data for review
- Export observations as CSV, GeoJSON, or Darwin Core Archive-compatible tables
- Manage sites, observers, species lists, and seasonal survey protocols
- Generate basic summaries by species, site, month, and survey year

## Install

### Requirements

- Python 3.11+
- PostgreSQL 14+ with PostGIS enabled
- Node.js 20+ for the web dashboard
- GDAL, required for spatial exports

### Backend

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

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
```

### Run Locally

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

The application will be available at:

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

## Usage

### 1. Create Survey Sites

Add survey locations from the admin dashboard or import them from a CSV file:

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

Expected columns:

```text
site_code,name,latitude,longitude,habitat,region
```

### 2. Configure a Survey Protocol

Protocols define how observations should be collected. A typical point count protocol includes:

- Survey window
- Count duration
- Distance bands
- Required weather fields
- Allowed breeding evidence codes
- Species checklist for the region

### 3. Start a Field Survey

Observers can create a new survey from the web dashboard or mobile field view. Each survey records:

- Site or route
- Date and start time
- Observer name
- Duration and distance
- Weather conditions
- Species observations
- Comments and uncertainty notes

### 4. Review Records

Project reviewers can inspect flagged observations before export. Records may be flagged when they include:

- Rare species for the region
- Counts above configured thresholds
- Missing effort information
- Coordinates outside the assigned survey site
- Observations outside the active survey season

### 5. Export Data

Export reviewed observations:

```bash
python manage.py export_observations --format csv --year 2026 --output exports/birds-2026.csv
```

Supported formats:

```text
csv
geojson
dwca
```

## Configuration

FieldFlock is configured with environment variables and optional YAML files.

### Environment Variables

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

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

Common settings:

```env
DATABASE_URL=postgres://fieldflock:fieldflock@localhost:5432/fieldflock
SECRET_KEY=change-this-in-production
DEBUG=true
ALLOWED_HOSTS=localhost,127.0.0.1
TIME_ZONE=America/Toronto
DEFAULT_COORDINATE_SYSTEM=EPSG:4326
MEDIA_ROOT=./media
EXPORT_ROOT=./exports
```

### Survey Protocols

Protocols are stored in `config/protocols.yml`:

```yaml
spring_point_count:
  name: Spring Point Count
  season_start: "2026-05-01"
  season_end: "2026-06-30"
  duration_minutes: 10
  distance_bands:
    - 0-50m
    - 50-100m
    - over-100m
  required_weather:
    - temperature_c
    - wind_beaufort
    - cloud_cover_percent
    - precipitation
  breeding_codes:
    - S
    - P
    - T
    - C
    - FY
    - FL
```

### Species List

Regional species lists can be imported from CSV:

```bash
python manage.py import_species data/species.csv
```

Expected columns:

```text
species_code,common_name,scientific_name,taxon_order,season_status,review_required
```

### Review Rules

Observation review thresholds are configured in `config/review_rules.yml`:

```yaml
rare_species:
  require_review: true

high_counts:
  AMRO: 200
  BCCH: 75
  COYE: 40

out_of_season:
  require_review: true
```

## License

This project is released under the MIT License.