# BirdWatch Survey

BirdWatch Survey is a citizen-science data collection tool for recording bird observations in local parks, wetlands, farms, schoolyards, and backyards. It helps volunteers submit structured survey checklists, attach location and weather context, and export records for review by regional coordinators.

The project is designed for small conservation groups that need a lightweight, auditable workflow without depending on a proprietary field-survey platform.

## Features

- Create timed bird-survey checklists with observer name, site, start time, duration, and distance traveled
- Record species counts, breeding behavior, confidence level, and optional notes
- Store GPS coordinates for survey sites and individual point-count locations
- Flag unusual species, high counts, and incomplete checklists for coordinator review
- Import species lists from CSV files
- Export observations as CSV or JSON for analysis in R, Python, QGIS, or spreadsheet tools
- Configure survey protocols for point counts, transects, backyard watches, or incidental sightings
- Run locally for field events, workshops, classrooms, and community science programs

## Install

### Requirements

- Node.js 20 or newer
- npm 10 or newer
- SQLite 3

### Setup

```bash
git clone https://github.com/example/birdwatch-survey.git
cd birdwatch-survey
npm install
cp .env.example .env
npm run db:migrate
npm run dev
```

The development server starts at:

```text
http://localhost:3000
```

### Production Build

```bash
npm run build
npm start
```

## Usage

### Create a Survey Site

1. Open the app in your browser.
2. Go to **Sites**.
3. Select **New Site**.
4. Enter the site name, habitat type, latitude, longitude, and access notes.
5. Save the site.

### Start a Checklist

1. Select a survey site.
2. Choose a protocol, such as `point_count` or `transect`.
3. Enter the start time, observer names, weather, and visibility.
4. Add each species observed with count and notes.
5. Mark the checklist as complete when the survey is finished.

### Import a Species List

Species lists must be CSV files with the following columns:

```csv
code,common_name,scientific_name,region,status
AMRO,American Robin,Turdus migratorius,northeast,common
NOCA,Northern Cardinal,Cardinalis cardinalis,northeast,common
```

Import with:

```bash
npm run import:species -- ./data/species.csv
```

### Export Observations

Export all reviewed observations:

```bash
npm run export -- --format csv --output ./exports/observations.csv
```

Export a single survey season:

```bash
npm run export -- --format json --season 2026 --output ./exports/season-2026.json
```

## Configuration

Configuration is handled through environment variables in `.env`.

```env
APP_NAME="BirdWatch Survey"
APP_PORT=3000
DATABASE_URL="file:./data/birdwatch.sqlite"

DEFAULT_REGION="northeast"
DEFAULT_TIMEZONE="America/Toronto"
REQUIRE_COORDINATES=true
ALLOW_INCIDENTAL_OBSERVATIONS=true

REVIEW_UNUSUAL_SPECIES=true
HIGH_COUNT_ALERT_THRESHOLD=75

EXPORT_INCLUDE_PRIVATE_NOTES=false
EXPORT_DATE_FORMAT="YYYY-MM-DD"
```

### Options

| Variable | Description | Default |
| --- | --- | --- |
| `APP_NAME` | Name shown in the app header and exports | `BirdWatch Survey` |
| `APP_PORT` | Local server port | `3000` |
| `DATABASE_URL` | SQLite database location | `file:./data/birdwatch.sqlite` |
| `DEFAULT_REGION` | Region used for species-list filtering | `northeast` |
| `DEFAULT_TIMEZONE` | Timezone used for survey timestamps | `America/Toronto` |
| `REQUIRE_COORDINATES` | Require coordinates for survey sites | `true` |
| `ALLOW_INCIDENTAL_OBSERVATIONS` | Allow non-protocol sightings | `true` |
| `REVIEW_UNUSUAL_SPECIES` | Flag rare or out-of-region species | `true` |
| `HIGH_COUNT_ALERT_THRESHOLD` | Count that triggers coordinator review | `75` |
| `EXPORT_INCLUDE_PRIVATE_NOTES` | Include internal notes in exports | `false` |
| `EXPORT_DATE_FORMAT` | Date format used in generated files | `YYYY-MM-DD` |

## Data Notes

BirdWatch Survey stores submitted records locally by default. Before sharing exported data publicly, remove private access notes, sensitive nest locations, and personally identifying observer details where required by your program policy.