Pet Care App Onboarding: From First Photo to Full Care Plan — PupPal

2026-08-27

Pet Care App Onboarding: From First Photo to Full Care Plan — PupPal

Most pet care apps ask you to do a lot of work before you get any value: create an account, verify an email, fill a six-screen profile, invite your household, read the feature tour, and only then — maybe — log your first walk. PupPal takes the opposite route. Pet care app onboarding in PupPal is designed so that a new owner goes from first launch to a working AI care system inside ten minutes, and the whole journey is anchored on one idea: the first photo is the onboarding. There is no account wall, no email verification, and no empty dashboard staring back at you. There is a camera button, a pet profile that takes under a minute, and an AI agent that starts building a care plan the moment the first photo lands. This post walks through the first ten minutes with PupPal exactly as the codebase builds them — the three-page launch intro, the pet profile webhook, the first photo pipeline, the 21:00 nightly review, and the care session that turns a solo owner into a care team. Every step below is real, taken from the production source in the PupPal repository.

The reason onboarding is shaped this way is architectural, not cosmetic. PupPal is an app where photo = check-in, share = care: a Flutter client talks to a Cloudflare Worker (R2 for photos, KV and Durable Objects for state) which relays webhooks to a self-hosted Hermes Agent that runs the AI skills — photo-analyze, daily-review, daily-voice, care-monitor, and care-handbook. Because the intelligence lives in that agent, the onboarding job is not to teach the user a workflow; it is to give the agent a pet to watch over. Everything in the first ten minutes exists to answer one question the agent asks before it can do anything useful: who is this dog, and what does normal look like for them?

Minute Zero: First Launch Skips the Friction

The very first frame of the app is a loading spinner, and that spinner is a deliberate design decision. On cold start, OnboardingPage immediately checks whether the user has already configured an AI engine by reading aiConfiguredProvider, which looks for an ai_active_track value in the local Isar key-value store, then falls back to a bring-your-own-key (BYOK) config. If anything is found, the user is an existing owner and the app skips the intro entirely — the code comment says it plainly: returning users jump straight to the home screen so the onboarding pager never flashes on screen for someone who has already been through it. New users, though, see a three-page introduction with a skip button on every page, and skipping is always allowed.

The three pages are short, visual, and each one previews a real feature rather than a slogan. Page one is AI Check-in — "Capture your puppy's best moments" — showing the camera icon that will become the home-screen check-in button. Page two is Pet Sitting — "Let a neighbor Pet Sitter care for your puppy" — previewing the care-code model where someone else can look after the dog without ever creating an account. Page three is AI Soul — "An AI agent gives your digital puppy a soul" — and it is the only page with a real decision on it. New users get two buttons: Set up AI now or Explore first. The "Set up AI now" path pushes the AI configuration page, where the owner brings their own API key — the engine supports local, Hermes, and cloud channels, with a test-connection step that verifies the key works before the app accepts it — and returns to complete onboarding. "Explore first" skips straight into the app; the AI pages stay reachable from settings later.

Two details make this intro feel honest rather than obstructive. First, the skip affordance is always visible except on the final page, where "Explore first" replaces it — the product never traps the user in a tour. Second, the flow is built so the user can never be asked to configure something twice: finishing onboarding writes a not_first_launch flag into a local config store, and the AI check runs before the pager renders, so the state machine always converges on the home screen. The entire minute-zero experience is a funnel with exactly one required action — tapping Get Started three times — and a configurable AI step that can be deferred forever. That is the whole point: in pet care app onboarding, the app must not demand setup work from someone who just wants to photograph their dog. The dog is the priority; the plumbing is optional.

The Pet Profile: One Form, One Webhook, One Memory

With onboarding complete, the new owner reaches the pet page and creates the dog's profile — the only form in the app that is actually required. The model behind it is a single Isar collection called Pet, and its fields tell you exactly what the product thinks matters about a dog: name (with a cheerful default of "dog1"), breed (typed in a text field with a breed-category picker), size via a dedicated input widget, weight, birthDate as an epoch timestamp, gender, an avatar photoPath, and colorValue for the pet's theme color. There is even a model3dStatus field (none, generating, ready, failed) for a future 3D model of the pet, and per-pet voice settings — a voiceTimbreIndex and a voiceKokoroSid so each dog gets its own sound in daily voice messages. The form is deliberately small: name, breed, size and a photo. Everything else about the dog comes later, from observation rather than interrogation.

The moment the owner saves, the app calls POST /puppal-init — the first webhook of the product's four-event lifecycle (puppal-init, puppal-photo, puppal-care-create, puppal-care-end). The payload is a complete pet dossier that most owners would never fill out voluntarily, which is why it is optional: breed, age, weight, gender, neutered status, and avatar URL, plus a feeding block (food brand, amount per meal, meal times, post-meal notes), a medications array (name, dosage, schedule, notes), allergies, a behavior block (friendliness with strangers, leash training, known commands, fears, quirks), the vet contact, an emergency_contact, and a personality block with tone and traits. The Cloudflare Worker validates the request, forwards it to the Hermes Agent, and the agent's puppal-init handler writes the profile directly into memory under dog:{dog_id}:profile with an initial state under dog:{dog_id}:state. The response comes back as "宠物档案已创建，Hermes 已就绪" — the pet file is created, Hermes is ready.

That one payload is the quiet engine of everything that follows. The care handbook that a future sitter will receive is generated from this profile, not from a questionnaire at handoff time. The daily-voice message the agent writes at 09:00 each morning draws on the personality traits ("贪吃", "粘人" — food-motivated, clingy) to sound like the actual dog. The daily-review feeding check compares detected eating scenes against the meal times stored here. The vet contact rides along in every care handbook so a sitter can find the right clinic without asking. In other words, the profile the owner fills in minute two is the seed of the entire care plan — the agent spends the rest of the dog's life filling in the details that this form deliberately leaves blank. This is the opposite of the classic onboarding trap where the app asks for everything up front and then does nothing with it. PupPal asks for almost nothing, and uses all of it.

The First Photo: Where the AI Actually Starts

The owner has now spent roughly three minutes in the app. The pet page shows a friendly prompt to take the first check-in photo, and this is the moment pet care app onboarding turns from a form into a system. The check-in flow behind the camera button supports several channels — a tap on a habit chip, a text description, or a photo — but the photo channel is the flagship, and it runs on the AI engine that ships inside the app itself, reached through a Rust → FRB → Flutter bridge. When the shutter fires, analyzePhoto makes one Vision call that returns three structured analyses at once: V2 posture (standing, sitting, lying, running, jumping, playing, eating, drinking, sleeping), V4 expression (happy, calm, alert, curious, tired, anxious, sad, playful), and V5 environment (indoor_home, outdoor_park, outdoor_street, car, vet). Token cost is defended hard before the call: the image's long edge is compressed to 1568 pixels, anything over 4MB is forced to JPEG, and a 30-second timeout protects against a hung network. The classification of which habit this check-in belongs to is deliberately zero-token, done on-device with string matching, which is how a photo check-in can cost a fraction of a cent.

But the very first photo is special, and the code treats it that way. In the full webhook pipeline — upload to R2, then POST /puppal-photo with the X-Webhook-Secret header — the photo-analyze skill hits a deliberate fork: if the pet does not exist in memory yet, this is the first check-in, so the agent skips the S1 baseline comparison and creates the initial state. There is no history to compare against, and the system refuses to fake one. The same honesty rule appears in the C7 anomaly detector, whose documentation notes that "new pets do not trigger behavioral anomalies in the first 7 days — there is no baseline to compare against." A first photo of a sleeping dog will not generate a false alarm about unusual napping, because the agent knows it has never seen this dog before. The C7 engine's first pass is still valuable though: it checks for visible wounds or skin issues flagged by the vision pass, environment hazards in the hazards_visible field, and anything the vision model describes as abnormal appearance.

What comes back from the agent is designed to feel like a friendly vet tech, not a JSON dump: a dog_state_snapshot with happiness, energy, and health_score, a trend_brief, and a warm message in the pet's voice — something like "豆豆 looks very happy! Resting on the living room floor. Everything normal ✓". Under the hood, that snapshot is built with a moving average that gives the newest observation a 0.3 weight (new_happiness = current * 0.7 + v4_score * 0.3), which means the state chases reality quickly without whipsawing on a single bad photo. The check-in also becomes a Play record in the habit layer — one row carrying the photo path, the AI's JSON, tokens used, cost in micro-dollars, and the channel that analyzed it (local, hermes, or cloud) — so the photo the owner took for fun is simultaneously feeding the health state, the habit streaks, and the daily review. The photo check-in deep dive traces this exact byte path; the onboarding-relevant part is that the first photo is not a demo — it is a real datum in a real baseline, and the app tells the owner so with the very first snapshot card.

The First Night: The Automation Begins at 21:00

By minute five, the owner has a pet profile, one photo check-in, and a snapshot of the dog's state. The app's job from here is to keep the loop running without being asked, and that is what the two cron jobs in the Hermes profile are for. Every day at 09:00, the daily-voice skill wakes up, reads the previous day's data, and writes a message in the pet's first person — a short monologue that sounds like the dog talking about its own day. Every day at 21:00, the daily-review skill runs the deeper machinery: it aggregates the day's photo analyses into S1 (baseline comparison of happiness, energy, and health against the trailing 7-day history), S3 (feeding confirmation, comparing detected eating scenes against the usual meal count and reporting normal, less, more, or unable_to_detect), and S4 (activity comparison against the 7-day average), then computes a weighted health score — 25 percent happiness, 30 percent anomaly-free, 15 percent energy, 15 percent feeding normality, 15 percent activity — and appends it to the dog's stats.history.

The nightly review is where a new owner first sees onboarding pay off, because it converts the day's photos into something actionable. If the health score declines three days running by a cumulative 0.2, or energy stays below 0.3 for three days, the agent raises a high-severity alert; a single-day happiness drop or an anomaly score above 0.5 gets a medium flag; three consecutive high-severity days triggers a recommendation to book a vet. None of this requires the owner to fill in a mood tracker or a food diary — the photos do the reporting. The first night after onboarding is necessarily thin (one photo, no history), but the review is honest about that too: it builds the baseline from whatever exists, and the nightly health review post explains the S1/S3/S4 math in full. What the owner notices on day one is simpler: at 09:00 the dog "speaks," at 21:00 the day gets summarized, and both arrive without a single tap. The onboarding promise "record pet life, build healthy habits" starts fulfilling itself on night one.

The habit layer is what makes the photos add up over time. Each check-in resolves against the dog's active habit instances — the two-layer model where 49 curated templates (feeding, walking, vet check-ups, and more, grounded in APPA market data) get copied into per-pet instances with their own goals, reminders, and streaks. An unmatched moment doesn't get lost: the recovery service either copies the closest template or creates a new habit from the AI's own summary, and startup recovery re-classifies any check-in that failed to sync while the network was down. For a brand-new owner, this means the app's habit list grows in the direction of the dog's real life rather than presenting a fixed menu on day one — the AI habit tracking post covers the full pipeline. The owner who started ten minutes ago with a single photo already has a streak of one, a baseline forming, and an agent that will quietly add habits as the dog's routine emerges from the photos.

The First Care Session: From Owner Only to Shared Care

Within the first ten minutes, the owner can also do the one thing that no other pet care app makes this easy: hand the dog to someone else. The care session flow is one button and one POST. The owner taps start care, the app calls POST /puppal-care-create with the dog id and the session window, and the Worker generates a care code — the format is memorable and scannable, like PUPPY-A7K3 — plus a four-digit PIN such as 3369. The agent immediately runs the care-handbook skill, building an instruction document from the dog's memory: feeding brand and portions, medication schedules, behavior notes, vet contact, and a closing message in the pet's voice thanking the sitter. The owner sends the code and PIN by any channel — WeChat, iMessage, or face to face — and the sitter is done. No account, no app install ritual: the sitter can even open the care page in a browser, type code plus PIN, and read the handbook.

This is the stage where pet care app onboarding becomes genuinely different, because the product was designed so that the care consumer never joins the product. The sitter's session shows the pet's photo, the handbook, and one big camera button; each sitter photo goes through the same pipeline under source: caregiver, but with care-monitor applying deliberately tighter anomaly thresholds — every alert threshold drops by 40 percent, because a dog in a strange environment under someone else's eye deserves extra sensitivity, not less. If the agent flags something, it alerts the owner immediately rather than waiting for the nightly review. The session dies cleanly: the owner ends it with puppal-care-end, the code expires, and the sitter's app screen switches to "this care session has ended" and stops accepting photos. The care codes deep dive explains the security model — the PIN is shown in plaintext exactly once, at creation — and the rescue dog foster post shows the tightened thresholds in action. For onboarding purposes, the point is timing: the owner learns the entire sharing model exists before the first day is out, because the feature is a button, not a setup flow.

Why does the care flow belong in an onboarding walkthrough at all? Because it completes the product's core sentence — photo = check-in, share = care — and a new owner who never learns that the sharing layer exists will discover it only when life forces an emergency: a trip, a hospital stay, a last-minute work event. PupPal's onboarding surfaces the capability early, in the second intro page, so that when the emergency comes the owner already knows the answer is a code and a PIN, not a panicked text chain of instructions. The care session is also the first time the AI's memory work is visibly handed to another human: the handbook the sitter receives is built from everything the check-ins and the profile have accumulated, which is exactly how AI pet companion onboarding should feel — the system, not the owner, does the briefing.

What the First Ten Minutes Are For

Look back at the whole arc and a design principle emerges: every onboarding step in PupPal either creates a pet in the agent's memory or is skippable. The intro is skippable. The AI configuration is skippable (and re-runnable later). The care session is optional. The only non-skippable step is the pet profile, because without a dog:{dog_id} there is nothing for Hermes to watch. Everything else is deferred value — and the product's bet is that the value compounds fast enough that owners come back voluntarily. Ten minutes in, the owner has: a pet profile seeded into agent memory, one analyzed photo that opened the health snapshot, the first night's review and voice scheduled automatically, and a care-code flow that turns any friend into a sitter without registration. That is a complete care plan in embryo, built from one form and one photo.

The deeper argument is about what onboarding should optimize in an AI product. Traditional pet apps optimize for data entry coverage — they want a complete profile so their features have something to chew on, and they front-load the questionnaire accordingly. PupPal optimizes for first successful action: get the owner to the camera, give them a meaningful AI response within seconds, and let the care plan assemble itself from the stream of check-ins that follows. The webhook-driven design post shows why this works at the architecture level — the four webhooks are the entire state machine, so onboarding is not a special flow bolted onto the product; it is just the first calls the app makes. The pet profile is puppal-init, the first photo is puppal-photo, and the first care session is puppal-care-create. Onboarding UX in PupPal is not a tour of features. It is the first three messages of a conversation between the owner, the worker, and the agent — and the agent never forgets a message.

So if you are setting up a dog care routine from scratch, the advice from the codebase is simple: skip the intro if you like, but do not skip the first photo. Fill in the breed, snap a check-in of the dog on the sofa, read the snapshot card when it comes back, and let the 21:00 review start counting. Ten minutes from now the agent will know your dog's name, your dog's normal, and your dog's voice — and that is the entire care plan that matters. The first photo is the only onboarding there is; everything after it is just care.

Set up PupPal today, take the first check-in, and watch the care plan build itself — one photo, one review, one voice message at a time.