# BirdWatch Survey

A citizen-science field survey app for collecting structured bird observations from volunteers, schools, conservation groups, and local birding clubs.

BirdWatch Survey helps participants record species sightings, counts, locations, habitat notes, survey effort, and optional media. Data can be exported for review or submitted to a central project database for long-term biodiversity monitoring.

## Features

- Guided bird survey forms for point counts, transects, and casual observations
- Species lookup using common and scientific names
- GPS location capture with manual location override
- Survey effort tracking, including start time, duration, distance, and observer count
- Optional notes for weather, habitat, behavior, breeding evidence, and confidence level
- Photo and audio attachment support
- Offline data entry with later sync
- CSV and GeoJSON export for analysis in spreadsheets or GIS tools
- Configurable species lists, survey protocols, regions, and validation rules

## Install

### Requirements

- Node.js 20 or newer
- npm 10 or newer
- PostgreSQL 15 or newer
- A Mapbox or OpenStreetMap-compatible tile provider, if using maps

### Setup

Clone the repository:

```bash
git clone https://github.com/example/birdwatch-survey.git
cd birdwatch-survey
```

Install dependencies:

```bash
npm install
```

Create a local environment file:

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

Initialize the database:

```bash
npm run db:migrate
npm run db:seed
```

Start the development server:

```bash
npm run dev
```

The app will be available at:

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

## Usage

### Create a Survey

1. Sign in with a project or volunteer account.
2. Select a survey type: `point_count`, `transect`, or `casual`.
3. Choose the survey site or allow the app to capture your current location.
4. Enter survey conditions such as weather, visibility, and habitat.
5. Record each species observed, including count and detection method.
6. Save the survey locally or submit it to the project database.

### Export Data

Export reviewed observations as CSV:

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

Export spatial records as GeoJSON:

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

### Run Tests

```bash
npm test
```

Run linting:

```bash
npm run lint
```

## Configuration

Application settings are managed through environment variables and project configuration files.

### Environment Variables

Create a `.env` file based on `.env.example`.

```env
DATABASE_URL=postgres://birdwatch:birdwatch@localhost:5432/birdwatch
APP_BASE_URL=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-value
MAP_TILE_URL=https://tile.openstreetmap.org/{z}/{x}/{y}.png
MEDIA_STORAGE_PATH=./uploads
ENABLE_OFFLINE_SYNC=true
DEFAULT_REGION=northeast
```

### Survey Protocols

Survey protocols are defined in:

```text
config/survey-protocols.json
```

Example:

```json
{
  "point_count": {
    "label": "Point Count",
    "defaultDurationMinutes": 10,
    "requiresEffort": true,
    "requiresWeather": true,
    "maxDistanceMeters": 100
  }
}
```

### Species Lists

Regional species lists are stored in:

```text
config/species/
```

Each file should include the species code, common name, scientific name, and optional seasonal status.

```csv
code,common_name,scientific_name,status
AMRO,American Robin,Turdus migratorius,resident
BCCH,Black-capped Chickadee,Poecile atricapillus,resident
YWAR,Yellow Warbler,Setophaga petechia,breeding
```

### Validation Rules

Observation validation settings are stored in:

```text
config/validation.json
```

Use this file to configure count limits, rare species flags, required review fields, and date-based seasonal warnings.