§ masterplan.md
Playful Pet Adoption Matchmaker
A cute, bouncy adoption site where visitors answer a short quiz to find their perfect rescue pet personality match.
01
App overview and objectives
An adoption site that starts with a lifestyle quiz instead of a photo grid, so people meet animals that actually fit their home. Success is measured in completed adoptions that do not come back.
02
The problem worth solving
Shelters lose animals to returns because adopters choose by cuteness. Matching on space, hours away from home, budget and experience makes the first match the last one.
03
Target audience
- Primary — First-time adopters unsure what kind of animal suits their life.
- Secondary — Shelter staff who spend hours screening unsuitable applicants.
04
Roles and permissions
- Visitor — read-only public pages, can sign up.
- Member — owns their own records, cannot see other users' data.
05
Core features
- Playful quiz covering home size, hours away, allergies, budget, experience
- Match results with a plain-language explanation of why each animal fits
- Animal profiles with medical history, temperament notes and video
- Application form pre-filled from quiz answers, with shelter review status
- Success stories wall with follow-up photos from adopters
- Donation and supply wishlist for the shelter
Deliberately later
- Foster coordination
- Post-adoption care reminders
- Multi-shelter network
06
Technical stack
React front end with a rules-based matching engine, Postgres, image and video storage.
Why: A transparent rules engine is better than a model here: shelters need to explain and tune why a match was made.
Alternatives: A machine-learned recommender (better with lots of data, opaque and cold-start hostile) or a plain filter list (simple, loses the emotional hook).
07
Conceptual data model
Animal — species, breed, age, size, energy, health, temperament tags, media, status
QuizResponse — session, answers, computed profile
Match — quiz response, animal, score, reasons
Application — adopter, animal, answers, status, shelter notes
Story — adopter, animal, photos, text, published
08
Integrations
- Image and video storage
- Email for application status
- Payments for donations
09
UI design principles
- Rounded shapes, bright accent colours, springy micro-animations on every tap.
- Reward progress visually — confetti, badges, character reactions.
- Copy is short, warm and second-person; never corporate.
10
Security considerations
- Adopter contact details visible only to the shelter handling the application.
- Moderate success stories before publishing.
- Do not expose exact shelter addresses for animals with a protection order.
11
Development phases
Phase 1 — Prove the core
- — Playful quiz covering home size, hours away, allergies, budget, experience
- — Match results with a plain-language explanation of why each animal fits
- — Animal profiles with medical history, temperament notes and video
- — Static content and design system in place
- — Basic analytics
Phase 2 — Make it real
- — Application form pre-filled from quiz answers, with shelter review status
- — Success stories wall with follow-up photos from adopters
- — Donation and supply wishlist for the shelter
- — Accounts, sign-in and password reset
- — Empty, loading and error states everywhere
Phase 3 — Polish and launch
- — Performance, accessibility and SEO pass
- — Legal pages, contact route and 404 handling
- — Wire up: Image and video storage
- — Wire up: Email for application status
Phase 4 — Grow
- — Foster coordination
- — Post-adoption care reminders
- — Multi-shelter network
12
Challenges and solutions
Risk — Quiz feels like a barrier
Solution — Six questions maximum, playful visuals, results in under a minute, browsing always available.
Risk — Shelter data entry burden
Solution — A phone-first intake form and bulk import from existing shelter spreadsheets.
Risk — Emotional pressure leads to bad matches
Solution — Show honest 'this animal may not suit you' warnings, not just positives.
13
Future expansion
- Vet partner directory
- Adoption-day event booking
- Lost-and-found board
14
Page list (13 pages)
- 01 PUBLIC Quiz — The lifestyle questionnaire and instant results.
- 02 PUBLIC Pets — Browse all animals with filters and match scores.
- 03 PUBLIC Success Stories — Proof and emotional pull from past adoptions.
- 04 PUBLIC Apply — Application form and status tracking.
- 05 PUBLIC Donate — Money and supply wishlist.
- 06 AUTH Sign up — Create an account with email or a social provider.
- 07 AUTH Log in — Return to the account, with error and lockout states.
- 08 AUTH Reset password — Request a reset link and set a new password.
- 09 APP (signed in) Account settings — Profile, email, password, language and delete account.
- 10 PUBLIC Contact — Contact form plus real address, phone and email.
- 11 LEGAL & SYSTEM Privacy policy — What data is collected, why, and how to remove it.
- 12 LEGAL & SYSTEM Terms of service — Rules of use, liability and account termination.
- 13 LEGAL & SYSTEM 404 not found — Friendly dead end with search and links back.
15
Page map
PUBLIC AUTH APP (signed in) LEGAL & SYSTEM ────────────────── ───────────────── ─────────────────── ─────────────────── ├─ Quiz ├─ Sign up └─ Account settings ├─ Privacy policy ├─ Pets ├─ Log in ├─ Terms of service ├─ Success Stories └─ Reset password └─ 404 not found ├─ Apply ├─ Donate └─ Contact key flows: Quiz ──▶ Pets Pets ──▶ Apply Success Stories ──▶ Donate