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

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.

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:

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_MONTHLY or STRIPE_PRICE_HOUSEHOLD_CONURE
• STRIPE_PRICE_HOUSEHOLD_CONURE_YEARLY
• STRIPE_PRICE_HOUSEHOLD_INDIANRINGNECK_MONTHLY or STRIPE_PRICE_HOUSEHOLD_INDIANRINGNECK
• STRIPE_PRICE_HOUSEHOLD_INDIANRINGNECK_YEARLY
• STRIPE_PRICE_HOUSEHOLD_MACAW_MONTHLY or STRIPE_PRICE_HOUSEHOLD_MACAW
• STRIPE_PRICE_HOUSEHOLD_MACAW_YEARLY
• 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.