Corey Blais
118 lines
4.5 KiB
Markdown
118 lines
4.5 KiB
Markdown
# 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`
|
|
- Stripe-ready per-flock billing identifiers so one account can manage multiple paid flock subscriptions
|
|
- 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`
|
|
|
|
## Stripe billing environment
|
|
|
|
Set these when the Stripe Checkout, Customer Portal, and webhook flow is enabled:
|
|
|
|
- `STRIPE_SECRET_KEY`
|
|
- `STRIPE_WEBHOOK_SECRET`
|
|
- `STRIPE_PRICE_HOUSEHOLD_CONURE`
|
|
- `STRIPE_PRICE_HOUSEHOLD_INDIANRINGNECK`
|
|
- `STRIPE_PRICE_HOUSEHOLD_MACAW`
|
|
- `STRIPE_CHECKOUT_SUCCESS_URL`
|
|
- `STRIPE_CHECKOUT_CANCEL_URL`
|
|
- `STRIPE_PORTAL_RETURN_URL`
|
|
|
|
## 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, Stripe checkout/customer portal/webhook flows, audit logging, and background reminder delivery before launch.
|
|
|
|
Stripe billing should be attached to `workspaces`, not `users`. Each flock has its own billing plan, subscription status, Stripe customer ID, and Stripe subscription ID, which lets one person own multiple household flocks with separate subscriptions while rescue flocks can stay on the free rescue path.
|
|
|
|
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.
|