Corey Blais
102 lines
3.7 KiB
Markdown
102 lines
3.7 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`
|
|
- 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.
|