# FlockPal

FlockPal is a Dockerized TypeScript app for tracking flock health with a clean, modern, and casual UI.

## Current scope

- Passwordless authentication only
- Magic-link email sign-in
- OAuth-ready login flow for Google, Microsoft, and Apple
- Multi-flock model with `standard` household and `rescue` modes
- Shared flock member management for both households and rescues
- Separate per-flock billing plan foundation with `rescue_free`, `household_basic`, `household_plus`, and `household_macaw`
- Bird profiles with name, tag ID, and species
- Bird DOB and gotcha day fields
- Daily weight recordings
- 30-day weight graph
- Vet visit history with notes
- Postgres-backed storage
- React frontend and Express backend
- Security-minded defaults like Helmet, CORS allow-listing, rate limiting, and input validation

## Planned next steps

- Medication and care reminders
- Invitation acceptance and onboarding polish for flock members
- Stripe or equivalent billing integration for paid household tiers
- Scheduled reminder delivery for birthdays, gotcha days, and care events
- Audit logging for flock access changes and bird transfers

## Development

1. Copy `.env.example` to `.env` if you want custom settings.
2. Start the development stack:

```bash
docker compose up --build
```

3. Open `http://localhost:3000`.
4. The API health check is available at `http://localhost:5000/api/health`.

Full API documentation is available in [docs/API_REFERENCE.md](docs/API_REFERENCE.md).

The default `docker-compose.yml` is development-only. It mounts source files, installs dev dependencies, and runs the backend and frontend in watch mode.

## Production

1. Set production values in your environment or `.env`, especially:
   - `POSTGRES_PASSWORD`
   - `FRONTEND_URL`
   - `BACKEND_URL`
   - `VITE_API_BASE_URL`
2. Build and start the production stack:

```bash
docker compose -f docker-compose.prod.yml up --build -d
```

3. The production backend runs the compiled Node app from `dist/app.js`.
4. The production frontend is built with Vite and served by Nginx on port `3000`.

## Auth and flock notes

- One user can belong to multiple flocks.
- A rescue member can also keep their own household flock separate from the rescue flock.
- Billing should attach to the household flock, not the user account.
- Rescue flocks stay on the free plan.
- Shared access is controlled by flock roles like `owner`, `assistant`, `caregiver`, and `viewer`.
- FlockPal no longer stores local passwords.
- Authentication now happens through magic links or external identity providers.

## OAuth environment

Set these in Docker or your `.env` file if you want provider login enabled:

- `FRONTEND_URL`
- `BACKEND_URL`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `MICROSOFT_CLIENT_ID`
- `MICROSOFT_CLIENT_SECRET`
- `APPLE_CLIENT_ID`
- `APPLE_CLIENT_SECRET`

## Magic-link email environment

Set these if you want magic links delivered by email instead of logged as a preview URL during local development:

- `SMTP_HOST`
- `SMTP_PORT`
- `SMTP_SECURE`
- `SMTP_USER`
- `SMTP_PASS`
- `SMTP_FROM_EMAIL`
- `SMTP_FROM_NAME`

## Notes for monetization and security

This starter now includes the account and flock foundation for monetization, but it still needs production-grade session hardening, invitation verification, billing integration, audit logging, and background reminder delivery before launch.

For account design, `standard` vs `rescue` is best treated as a flock type, not as a user role. If paid plans are added later, a separate `admin account mode` is usually less flexible than flock roles such as `owner`, `assistant`, `caregiver`, and `viewer`. That lets the same underlying account system work for both households and rescues without splitting product logic into unrelated account classes.