# 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-workspace model with `standard` household and `rescue` modes
- Shared workspace member management for both households and rescues
- Separate per-workspace billing plan foundation with `rescue_free`, `household_basic`, and `household_plus`
- 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 workspace members
- Stripe or equivalent billing integration for paid household tiers
- Scheduled reminder delivery for birthdays, gotcha days, and care events
- Audit logging for workspace access changes and bird transfers

## Run locally

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

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

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

## Auth and workspace notes

- One user can belong to multiple workspaces.
- A rescue member can also keep their own household flock in a separate workspace.
- Billing should attach to the household workspace, not the user account.
- Rescue workspaces stay on the free plan.
- Shared access is controlled by workspace roles like `owner`, `manager`, `staff`, 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 workspace 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 workspace type, not as a user role. If paid plans are added later, a separate `admin account mode` is usually less flexible than workspace roles such as `owner`, `manager`, `staff`, and `viewer`. That lets the same underlying account system work for both households and rescues without splitting product logic into unrelated account classes.