Files
FlockPal/docs/BEHAVIOR_JOURNAL.md
Corey Blais 3237cd7601
Deploy / deploy-prod (push) Skipped
Deploy / deploy-dev (push) Successful in 4m18s
Added behavior journal, adjusted layout, and added some colors
2026-10-05 15:20:00 -04:00

5.1 KiB
Raw Permalink Blame History

Behavior Journal

Open Flock → select a bird → Behavior Journal (calendar tab). Select a behavior or create a custom one, confirm the current date/time, and save. Duration in seconds, intensity from 1–5, and notes are optional. Open a day's occurrence to see its details, edit it, or delete it with confirmation.

The bird and behavior selectors filter the journal. The calendar displays one month at a time, daily counts and up to three dots (plus a + for additional events). Select a day to review its individual events. The count above the calendar reflects the selected behavior and displayed month.

Storage and access

The existing ensureSchema startup migration creates behavior_types and behavior_occurrences and idempotently seeds nine common behaviors. No separate migration command is required. Occurrences reference existing birds and normalized behavior types. They retain TIMESTAMPTZ occurrence, created, and updated timestamps; optional duration in seconds; optional intensity; and notes. Indexes support bird/date and bird/behavior/date queries.

Custom behavior names are reusable within a flock and unique ignoring case. Default types are explicitly marked so orphaned custom types never become public. A transferred bird retains its occurrences and the types used in those occurrences, even if its old flock is deleted. Other custom types from its former flock remain private.

Existing session/integration-token authentication, flock roles, subscription restrictions, memorialized-bird restrictions, and audit logging apply. Owners, assistants, and caregivers can record/edit/delete; viewers can read. Queries and mutations check the bird's current flock. Writes also check flock ownership and memorialization inside the SQL statement.

The browser uses its device time zone for entry and calendar grouping, consistently with local date/time controls. Month boundaries are converted to UTC for the API's inclusive from, exclusive to range. Stored timestamps are not replaced by dates or daily totals. An unchanged edit retains the original timestamp, including sub-second precision. During a daylight-saving repeated hour, a newly entered ambiguous local time uses the browser's earlier offset; an existing event retains its original instant when its time is unchanged.

This feature records observations and occurrence timing. It adds no diagnostic interpretation or behavioral analysis.

API

The interactive API reference includes these endpoints:

Method Path Purpose
GET /api/birds/:birdId/behavior-types Available default, flock, and transferred-history types
POST /api/birds/:birdId/behavior-types Create/reuse a custom type (name, optional description)
GET /api/birds/:birdId/behaviors?from=…&to=…&behaviorTypeId=… Events in a positive range of at most 32 days; optional type filter
POST /api/birds/:birdId/behaviors Create an occurrence
PUT /api/birds/:birdId/behaviors/:occurrenceId Replace the editable fields
DELETE /api/birds/:birdId/behaviors/:occurrenceId Delete an occurrence

Occurrence input: behaviorTypeId, offset-bearing occurredAt, optional/null durationSeconds (positive, at most one year), severity (integer 1–5), and notes (at most 10,000 characters). Responses include the behavior name and timestamps, allowing complete details to open without another request.

Isolated verification

Use a disposable copy/install when the local dependency or build directories belong to a container. Do not point these scripts at a real flock database. The integration scripts use fixed test-only database settings on port 55439 and API port 55440. They create fixtures with distinct flock IDs and leave them in the disposable database for inspection.

docker run --detach --rm --name flockpal-behavior-test-db \
  -e POSTGRES_PASSWORD=behavior_test_only -e POSTGRES_DB=behavior_test \
  -p 127.0.0.1:55439:5432 postgres:16-alpine
cd backend
npm ci
npm run build
npm test
node test-integration/behaviorJournal.mjs

The API integration check covers schema repeatability, seeded/custom types, duplicate custom names, independent events, create/edit/delete, bird/behavior/month filters, timestamp precision, invalid inputs, unauthenticated requests, viewer/read-only/memorialized restrictions, cross-flock access, and transfer history.

For the optional browser check, install Playwright in a disposable frontend install (it is not an application dependency), with the built backend alongside it:

cd ../frontend
npm ci
npm run build
npm install --no-save --package-lock=false playwright
npx playwright install chromium
node test-integration/behaviorJournal.mjs

The browser check starts and stops its own API and Vite server (port 55441). It covers the complete entry/custom behavior/edit/delete workflow, bird and behavior filters, day selection and daily counts, month navigation, local midnight and daylight-saving boundaries, and a 390px mobile layout. It writes screenshots to /tmp/flockpal-behavior-mobile.png and /tmp/flockpal-behavior-desktop.png.

After verification, stop only the disposable database:

docker stop flockpal-behavior-test-db