Platform and user interaction

Overview

This document defines how users interact with PetFolio across devices, connectivity conditions, and physical contexts. These are user requirements, not technical decisions - the engineering approach (native app, PWA, responsive web, etc.) is a separate decision that follows from these requirements.

Discovery

Job stories

Accessing on mobile:

• When I am on a walk with a dog I am sitting, I want to quickly check the walk protocol on my phone, so I know how to handle the situation without stopping for long.
• When I am at the vet with my pet, I want to pull up their health information on my phone, so I can share it with the vet without trying to remember details.
• When I am creating a profile for my pet, I want to do it on my phone, so I can fit it into my day without needing to sit at a desk.
• When I take a photo of my pet, I want to upload it directly from my phone camera, so I do not have to transfer it to another device first.

Accessing offline:

• When I am on a walk in an area with poor mobile signal, I want to check the dog's behaviour notes, so I know how to handle a situation even without internet.
• When the wifi goes down at my house while the sitter is staying, I want them to still have access to the profiles, so care is not disrupted by a connectivity issue.
• When I make changes to a profile while offline, I want those changes saved and synced when I am next connected, so I do not lose my work.

Quick reference:

• When I am looking after someone's pet and need to check a specific detail (feeding time, medication dose), I want to find it within seconds, so I am not scrolling through the entire profile under pressure.
• When I open PetFolio on my phone for the tenth time today, I do not want to sign in again, so I can get the information I need without friction.

Professional desktop use:

• When I am working at a rehoming centre on a shared computer, I want to sign in as myself, so my actions are attributed to me and I see the right permissions.
• When I finish my shift and leave the shared computer, I want to be confident my session has ended, so the next person does not accidentally act as me.

The "5 Whys" - digging deeper

Starting statement: "PetFolio needs to work offline."

1. Why? - "Because users cannot guarantee a good internet connection."
2. Why does that matter? - "Because a sitter on a walk with poor signal still needs to know the walk protocol, the reactivity information, and what to do in specific situations."
3. Why can't they just check before they leave? - "Because they will forget details, or a situation will arise they did not anticipate. The whole point of the profile is that it is there when you need it."
4. Why can't they just call the owner? - "Because the owner might be on a plane, or in a meeting, or asleep in a different timezone. The profile exists precisely so the carer does not need to rely on the owner being available."
5. Why does it need to be on their phone? - "Because that is what they have with them. A printed document works offline, and PetFolio must be at least as reliable as a printed document."

Root requirement: PetFolio must work offline because it replaces printed care documents, and any situation where paper would have worked but PetFolio does not is a failure of the core value proposition.

Starting statement: "Authentication should differ by device context."

1. Why? - "Because a personal phone and a shared office computer have different security needs."
2. Why does that matter? - "Because on a personal phone, the device itself provides security (biometrics, PIN). On a shared computer, the device provides no security - the application must."
3. Why can't we just use the same approach everywhere? - "Because forcing sign-in every time on mobile kills the quick-reference use case. And staying logged in on a shared desktop means the next person inherits someone else's session and permissions."
4. Why is that dangerous? - "Because a Viewer at a rehoming centre could accidentally see an Editor's session and make changes they are not authorised to make. Or sensitive animal health data could be visible to someone who should not see it."
5. Why not just make everyone sign in every time? - "Because the sitter checking 'what time is dinner' for the fifth time today will stop using PetFolio and go back to the printed sheet on the fridge. Convenience is not a luxury - it is an adoption requirement."

Root requirement: Authentication must adapt to the device context because security and convenience are not in opposition - they have different correct answers depending on who owns the device.

Event storming

Event	Who triggers it?	Who cares?	What happens next?	What could go wrong?
App opened on mobile (online)	User	The user	Latest data synced, profile displayed	Slow connection causes long load time, user gives up
App opened on mobile (offline)	User	The user	Cached data displayed, sync queued for when online	Cache is stale, user sees outdated information (e.g., medication changed but cached version shows old dosage)
App opened on shared desktop	User	The user, previous user	Login screen shown, no persisted session	Previous user's session not fully cleared, new user sees wrong account
Profile edited while offline	User	The user, share recipients	Changes saved locally, queued for sync	User assumes changes are live but recipients still see the old version
Device comes back online after offline edits	System	The user, share recipients	Queued changes pushed to server, recipients see updates	Sync fails silently, user thinks changes were saved
Sync conflict detected	System	The user	Conflict resolution flow triggered (approach TBD)	User's changes overwritten without warning, data lost
Inbound sync detects profile change	System	The user viewing the profile	Updated data pulled to device	User mid-read sees content change unexpectedly
Session expired on personal device	System	The user	Biometric re-authentication prompted	User cannot authenticate (biometrics fail, device PIN forgotten)
Session expired on shared desktop	System / user logs out	The user, next user	Session cleared, login screen shown	Session data not fully cleared from browser
User switches context (Personal to Professional)	User	The user	Dashboard changes to show organisation's animals and role-appropriate actions	Context switch is slow, confusing, or loses unsaved work
Photo uploaded from camera	User	The user, the animal profile	Image captured, compressed, attached to profile	Image too large, upload fails on poor connection, format not supported
User searches animal list (Professional)	User	The user	Filtered results displayed	No results found, filters too restrictive, search is slow on large lists

Requirement highlights

MVP

• Mobile-first design (creation, sharing, and consumption primarily on phones)
• Offline access for profile reading and reference
• Data-conscious sync (lightweight inbound checks, push on user action outbound)
• Context-aware authentication (biometrics on personal devices, sign in/out on shared devices)
• Section-based navigation within profiles (Personal accounts)
• Filterable animal list with text search and multi-choice filters (Professional accounts)
• Guided prompt onboarding (same pattern as pet profile creation)
• Photo upload from phone camera

See MVP deep dive for detailed requirements.

Future

• Push notifications (phase 2)
• Calendar integration
• App intro/walkthrough after account creation
• Location/area grouping for Professional accounts
• Assigned carer grouping
• Configurable custom fields for Professional accounts
• Draft/publish model for controlling when edits become visible to share recipients

Application structure: single app or app per account type?

During discovery, the question arose: should PetFolio Personal (for individual pet owners) and PetFolio Business (for organisations) be separate applications or a single unified application?

Signals toward separate applications

• Different primary devices (phone vs desktop/tablet)
• Different authentication models (biometrics on personal devices vs sign in/out on shared desktops)
• Different usage patterns (quick dip-in/out vs sustained admin sessions)
• Existing wireframes already used separate domains (app.petfolio.com vs businessname.petfolio.com)
• Different scale (3 pets vs 200 animals)

Signals toward a single application

• For MVP, both account types do the same thing (create and share pet profiles)
• Sole traders and small professionals (freelance sitter, mobile groomer) have usage patterns closer to Personal than large organisations
• Cross-account sharing (owner shares with vet) is simpler within one system
• One codebase to maintain, one product to onboard users into
• Branded subdomains as a premium tier weakens the need for separation - not every Professional needs their own space

Decision

Single application with context switching. PetFolio is one application that serves both Personal and Professional account types. Users who belong to both (e.g., a vet nurse with personal pets and a staff role at a practice) switch between contexts within the same application.

Branded subdomains as a premium feature

Professional accounts can optionally have a branded subdomain (e.g., happypaws.petfolio.com) as a premium/paid feature. This is not required for Professional accounts to function.

Tier	Access point	Who it serves
Personal	app.petfolio.com	Individual pet owners
Professional (standard)	app.petfolio.com (context switch)	Sole traders, small professionals
Professional (premium)	businessname.petfolio.com	Larger organisations wanting branded space

Cross-account membership

A single person can have both a Personal account and be a staff member on a Professional account, using the same email address. They switch between contexts within the app. This resolves the constraint identified in ADR-001 where one email could only belong to one account.

Open technical decisions

Spike required: platform delivery

The platform delivery approach (native mobile app, progressive web app, responsive web with offline capability, or hybrid) is an open technical decision. The user requirements defined in this document - particularly offline access, biometric authentication, home screen installation, and photo upload - should inform the spike. This is an engineering investigation, not a product decision.

Spike required: context switching

How context switching between Personal and Professional accounts is implemented (within the same session, separate logins, etc.) depends on the platform delivery approach above.