# OpenFlock Survey

OpenFlock Survey is an open-source toolkit for collecting and validating community bird observations. It helps volunteers record standardized surveys in the field and gives project coordinators a reproducible workflow for exporting data for research, conservation planning, and public reporting.

The project is designed for point counts and walking transects, including surveys conducted offline in areas with limited connectivity.

## Features

- Record species, count, time, location, and optional breeding evidence
- Support point-count and transect survey protocols
- Capture survey effort, weather, habitat, and observer details
- Save observations offline and synchronize them later
- Validate required fields, coordinates, dates, and species codes
- Flag unusual counts or out-of-range species for review
- Import approved regional species checklists
- Export observations as CSV or GeoJSON
- Remove precise coordinates from public exports for sensitive species
- Run locally for training, testing, or small community projects

## Requirements

- Node.js 20 or newer
- npm 10 or newer
- PostgreSQL 15 or newer

## Install

Clone the repository and install its dependencies:

```bash
git clone https://github.com/openflock/openflock-survey.git
cd openflock-survey
npm install
```

Create a local environment file:

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

Create the database, apply migrations, and load the default species checklist:

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

Start the development server:

```bash
npm run dev
```

Open `http://localhost:3000` in a browser.

## Usage

### Create a survey

1. Sign in and select **New survey**.
2. Choose a survey site and protocol.
3. Record the start time, weather, habitat, and observer information.
4. Add each bird detected by sight or sound.
5. Record zero observations when a completed survey detects no birds.
6. Review validation warnings and submit the survey.

Draft surveys remain available on the device when offline. Synchronization begins automatically when a connection is restored.

### Import sites

Survey coordinators can import sites from a UTF-8 CSV file:

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

The file must contain the following columns:

```csv
site_id,name,latitude,longitude,protocol
ON-001,Riverside Marsh,43.6124,-79.4821,point_count
ON-002,North Woodlot,43.6488,-79.4175,transect
```

Coordinates must use decimal degrees in WGS 84.

### Export observations

Export all reviewed observations:

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

Generate a public GeoJSON export with sensitive locations obscured:

```bash
npm run export -- --status reviewed --format geojson --public --output ./exports/public.geojson
```

### Run checks

```bash
npm test
npm run lint
npm run typecheck
```

## Configuration

Configuration is read from `.env`. Restart the server after changing these values.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `SESSION_SECRET` | Yes | — | Secret used to sign session cookies |
| `APP_URL` | Yes | `http://localhost:3000` | Public URL of the application |
| `PORT` | No | `3000` | HTTP server port |
| `PROJECT_NAME` | No | `OpenFlock Survey` | Name shown in the interface and exports |
| `DEFAULT_TIMEZONE` | No | `UTC` | IANA timezone used when a site has no timezone |
| `DEFAULT_PROTOCOL` | No | `point_count` | Protocol selected for new surveys |
| `SPECIES_CHECKLIST` | No | `config/species.csv` | Path to the active species checklist |
| `REQUIRE_GPS_ACCURACY_METERS` | No | `50` | Maximum accepted GPS uncertainty |
| `SENSITIVE_SPECIES_FILE` | No | `config/sensitive-species.csv` | Species whose public coordinates are obscured |
| `PUBLIC_LOCATION_PRECISION_KM` | No | `10` | Grid size used to obscure public locations |
| `ALLOW_PUBLIC_REGISTRATION` | No | `false` | Allow volunteers to create their own accounts |
| `LOG_LEVEL` | No | `info` | Logging level: `debug`, `info`, `warn`, or `error` |

Example development configuration:

```dotenv
DATABASE_URL=postgresql://openflock:openflock@localhost:5432/openflock
SESSION_SECRET=replace-this-with-a-long-random-value
APP_URL=http://localhost:3000
PROJECT_NAME=Harbour Watershed Bird Survey
DEFAULT_TIMEZONE=America/Toronto
DEFAULT_PROTOCOL=point_count
REQUIRE_GPS_ACCURACY_METERS=50
ALLOW_PUBLIC_REGISTRATION=true
LOG_LEVEL=debug
```

Never commit `.env`, participant contact details, unpublished nesting records, or unredacted sensitive-species coordinates to version control.