Account and user management

Overview

Account and user management is the foundation of PetFolio. Every other feature area depends on it.

PetFolio has two account types that reflect fundamentally different relationships with animals:

• Personal - an individual managing their own pets. One person, one account. Household members and family get access to animal profiles via Profile Sharing.
• Professional - an organisation managing animals at scale. The account represents the organisation, and staff are members of it. Animals belong to the organisation, not to any individual.

Discovery

Job stories

Account creation:

• When I discover PetFolio for the first time, I want to create an account quickly using my existing Google login, so I can start building my pet's profile without a lengthy sign-up process.
• When I create a Personal account, I want to provide my basic details and start adding animals immediately, so I am not blocked by unnecessary setup steps.
• When I create a Professional account for my organisation, I want to set up the organisation's details and invite my first team members, so we can start working together quickly.
• When I sign up, I want to indicate whether I am a personal user or an organisation, so PetFolio can tailor my experience appropriately.

Authentication:

• When I return to PetFolio after being away, I want to sign in quickly and securely via OAuth, so I can get to my information without unnecessary friction.
• When I am on a shared or public device, I want confidence that my session will expire, so I do not worry about someone else accessing my pets' records.

Personal account - sharing with household:

• When my partner also needs access to our pets' profiles, I want to permanently share specific animals with their PetFolio account, so they can view the same information I can.
• When my household situation changes and someone should no longer have access, I want to revoke their permanent share, so my animals' information is protected.
• When I have an animal that I do not want to share with anyone in my household, I want to keep it private on my account only, so I have control over what is visible to others.

Professional account - staff management:

• When a new volunteer joins our rehoming centre, I want to invite them to our PetFolio account, so they can immediately view the animals in our care.
• When a staff member leaves the organisation, I want to remove their access in one action, so they can no longer view any of our animal records.
• When a trusted team member needs to update animal profiles, I want to promote them to Editor, so they can make changes without me having to do everything myself.
• When I am the only Owner/Admin and I go on holiday, I want confidence that my Editors can keep animal profiles up to date, so care is not disrupted by my absence.

Profile management:

• When I look at my own account, I want to see and update my contact details and emergency contacts, so the information is current for anyone I share with.
• When I manage a Professional account, I want to update the organisation's name, type, and contact details, so recipients of shared profiles see accurate information about who we are.

The "5 Whys" - digging deeper

Starting statement: "We need two account types."

1. Why? - "Personal users and organisations use PetFolio differently."
2. Why does that matter? - "A pet owner's animals belong to them personally. A rehoming centre's animals belong to the organisation. If the centre's manager leaves, the animals stay with the centre."
3. Why can't we just use one account type with sharing? - "Because sharing is per-animal, per-recipient. A rehoming centre with 200 animals and 15 staff would need 3,000 individual shares. And when the manager leaves, who owns the animals?"
4. Why is ownership important? - "Because the owner controls who sees the information. If ownership is tied to a person who leaves, access breaks for everyone."
5. Why can't we just transfer ownership? - "Transfer is one part of the solution, but the root issue is that organisational animals should never be tied to an individual in the first place. The organisation must be the owner."

Root requirement: Professional accounts must exist because organisational animals belong to the organisation, not to any individual within it. Tying ownership to a person creates a single point of failure that breaks access when people leave.

Starting statement: "Recipients need PetFolio accounts."

1. Why? - "The owner needs to know exactly who has access to their animal's information."
2. Why does that matter? - "Anonymous link-based sharing means anyone with the link can view the profile. Links get forwarded, bookmarked, or left open on shared devices."
3. Why is that a problem? - "Pet profiles contain sensitive information - health conditions, daily routines, home details, emergency contacts. The owner should control who sees it by name, not by link."
4. Why can't we just make links hard to guess? - "Because the sharing model needs to support permanent shares, editor rights, ownership transfer, and notes in future. All of those require known users on both sides."
5. Why build for the future now? - "Because retrofitting identity onto an anonymous system is far harder than starting with it. Users who signed up anonymously would need to create accounts later, and all their share history would need migrating."

Root requirement: Recipients need accounts because PetFolio's sharing model is built on known identities, not anonymous access. This enables the current feature set and provides a foundation for future capabilities without retrofitting.

Event storming

Event	Who triggers it?	Who cares?	What happens next?	What could go wrong?
Personal account created	New user	The user	OAuth sign-in, account type selected, profile details captured, empty animal list shown	Duplicate accounts (same person, different OAuth providers)
Professional account created	New user	The user, future staff	OAuth sign-in, account type selected, organisation details captured, staff invitation flow available	Organisation already has an account, user creates a duplicate
User signed in	Returning user	The user	Session created, appropriate dashboard shown (personal animals or organisation animals)	OAuth provider unavailable, session expired
User signed out	The user	The user, session security	Session terminated, all local state cleared	Session not fully cleared on shared device
Staff member invited	Owner/Admin	The invited person, existing staff	Invitation sent, pending state created	Wrong email, person already has a Personal account (can they also be on a Professional account?)
Staff member joined	Invited person	Owner/Admin, existing staff	User appears on staff list with Viewer role by default	Role assigned incorrectly, user expects immediate edit access
Staff member promoted to Editor	Owner/Admin	The promoted user	User can now create and edit animal profiles	Accidental promotion, no confirmation step
Staff member demoted to Viewer	Owner/Admin	The demoted user	Edit access revoked, user can only view	User had unsaved edits, work lost
Staff member removed	Owner/Admin	The removed user, remaining staff	All access to organisation's animals revoked immediately	Accidental removal, no confirmation step
Account profile updated	Account holder	Anyone they share with	Updated contact details or emergency contacts visible on shared profiles	Critical contact info deleted accidentally
Organisation profile updated	Owner/Admin	Staff, anyone with shared access	Updated org name, type, or contact details visible everywhere	Org name changed confuses existing share recipients

Requirement highlights

MVP

• Two account types: Personal and Professional, selected at sign-up
• OAuth authentication (Google first)
• Recovery email captured at sign-up
• Cross-account membership (same email can hold a Personal account and be staff on a Professional account)
• Personal account profile: name, email, phone, emergency contacts
• Professional organisation profile: name, type, contact details
• Professional staff roles: Owner/Admin, Editor, Viewer (Option A)
• Account lifecycle: Active, Inactive, Closed states with grace periods
• Account closure: Personal requires animals resolved; Professional requires account empty (all staff removed, all animals resolved)
• Account recovery via recovery email, support-assisted as fallback

See MVP deep dive for detailed requirements.

Future

• Admin role (Option B) - separate Owner and Admin roles for Professional accounts
• Property/home information for house sitters
• Multiple OAuth providers (Microsoft, Facebook)
• Staff notes on animal profiles
• Task management for Professional accounts