FlockPal/README.md

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, 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 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:

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.