# FlockWatch Survey

FlockWatch Survey is a citizen-science bird survey application for organizing field counts, recording sightings, validating observations, and exporting survey data for analysis or sharing with conservation partners.

## Overview

The project supports structured bird monitoring programs such as point counts, transects, backyard surveys, seasonal atlases, and habitat-specific studies. Volunteers can record observations in the field, including species, count, location, time, behavior, breeding evidence, habitat notes, and weather conditions.

Data reviewers can flag unusual records, correct taxonomy, and export clean datasets for reporting.

## Features

- Offline-ready field survey forms
- Point count, transect, and incidental observation workflows
- GPS coordinates and optional track recording
- Species search using a configurable taxonomy list
- Photo, audio, and note attachments
- Automatic date, time, and observer metadata
- Review flags for rare species, high counts, and out-of-range records
- CSV and GeoJSON exports
- Configurable survey regions, protocols, and validation rules

## Install

### Requirements

- Node.js 20+
- pnpm 9+
- PostgreSQL 15+ with PostGIS enabled

### Setup

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

The development server starts at:

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

## Usage

### Create a Survey

1. Sign in as an administrator.
2. Create a survey project and choose a protocol.
3. Define survey locations, date ranges, and volunteer access.
4. Publish the survey when it is ready for field collection.

### Record Observations

1. Open the field app on a phone, tablet, or laptop.
2. Select a survey location.
3. Start a point count or transect.
4. Add each bird observation with species, count, distance, behavior, and notes.
5. Submit the checklist when the survey is complete.

### Review and Export Data

```bash
pnpm export --format csv --survey spring-marsh-count
pnpm export --format geojson --survey spring-marsh-count
```

Exports are written to the configured export directory.

## Configuration

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

| Variable | Description | Default |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `APP_BASE_URL` | Public application URL | `http://localhost:3000` |
| `DEFAULT_TIMEZONE` | Timezone used for survey timestamps | `America/Toronto` |
| `SURVEY_REGION` | Default region code for validation rules | `CA-ON` |
| `TAXONOMY_FILE` | Path to the species taxonomy CSV | `data/taxonomy/birds.csv` |
| `MAP_TILE_URL` | Tile server URL for field maps | OpenStreetMap tiles |
| `ENABLE_GPS_TRACKS` | Enable GPS track recording | `true` |
| `MAX_OFFLINE_DAYS` | Number of days surveys can remain offline | `14` |
| `EXPORT_DIR` | Directory for generated exports | `exports` |
| `SMTP_HOST` | Mail server host for notifications | Optional |
| `SMTP_FROM` | Sender address for notification emails | Optional |

Example:

```env
DATABASE_URL=postgres://flockwatch:flockwatch@localhost:5432/flockwatch
APP_BASE_URL=https://survey.example.org
DEFAULT_TIMEZONE=America/Toronto
SURVEY_REGION=CA-ON
TAXONOMY_FILE=data/taxonomy/north-america-birds.csv
ENABLE_GPS_TRACKS=true
EXPORT_DIR=exports
```

## License

MIT