Aluvi — Product Requirements Document

Version: v1.8

Product: Aluvi iOS App

Platform: Swift (iOS)

MVP Scope: v1.0

Product Owner: Ardho

Date: April 2026

Last Updated: June 2, 2026

Status: Approved

Document Structure

Section 01 — Overview

Aluvi is an AI-powered skincare routine builder for iOS. It takes a user's skin type, concerns, budget, and products they already own — and generates a clear, personalized AM & PM routine in under 60 seconds. The app also flags ingredient conflicts, recommends missing products with affiliate links, and helps users stay consistent with their routine.

This PRD covers the MVP v1.0 scope, intended for handoff to the iOS (Swift) development team. Android is out of scope for MVP. The MVP targets the US market, English language only.

Section 01 — Problem Statement

The problem we're solving

US skincare consumers are overwhelmed. They watch TikTok tutorials, read Reddit threads, buy recommended products — and still don't know how to build a routine that works. The core problem is not lack of information. It's too much unstructured information with no clear, personalized path to action.

Market context

"Spent $200 on products and my skin is still breaking out."

— Common sentiment across r/SkincareAddiction, r/beauty, r/acne

Five core pain points (validated by Reddit research)

Pain 01 — Routine order confusion

Users don't know what order to apply products in, or whether AM and PM routines should differ. This is the single most common recurring question across skincare subreddits.

Pain 02 — Product overload

Users buy products based on TikTok and Reddit recommendations but can't figure out how to combine them into a coherent system. Information abundance does not equal confidence.

Pain 03 — Ingredient conflict anxiety

Fear of mixing actives incorrectly — retinol + AHA, vitamin C + niacinamide — and damaging the skin barrier. Users want reassurance, not just ingredient lists.

Pain 04 — Budget constraints

Especially acute among 18–28 users. They need the shortest path to an effective routine — not another shopping list that requires more spending.

Pain 05 — Desire for simplicity over complexity

Simplified routines are consistently recommended across beauty communities over complex ones. Consistency matters more than novelty. Fewer steps = easier to maintain.

Section 01 — Competitive Landscape

Existing alternatives and their limitations

Aluvi's white space

Existing tools cluster around one of: ingredient lookup, barcode scanning, toxic/clean labeling, routine logging, or product database reference.

Aluvi's most defensible position: Turn a user's current products, goals, and budget into a clear AM & PM routine with conflict awareness — in 60 seconds. No other app in the US App Store does this as its primary function.

Aluvi's strongest wedge is not "AI skincare expert."

It's routine clarity from chaos.

Section 01 — User Personas

Three primary personas for MVP v1. All share the same core frustration: they have products, they've done research, but they still don't have a clear routine.

Persona 01 — Sophia, 23 · "The Overwhelmed Beginner"

• Location: New York
• Occupation: College student
• Skin type: Acne-prone, combination
• Tags: Budget-conscious · TikTok-influenced · Has too many products

Background:

Sophia discovered skincare through TikTok. She's bought 6–8 products over the past year based on creator recommendations — The Ordinary niacinamide, CeraVe cleanser, a vitamin C serum, a retinol. She doesn't know what order to use them, whether to use all of them, or if some of them are canceling each other out.

Goals:

• Understand what to use in the morning vs at night
• Know which products to stop using together
• Keep her routine simple — she won't stick to anything with more than 4–5 steps

Frustrations:

• "I've watched so many videos and I still don't know what I'm doing"
• Scared to mix the wrong actives and break out worse
• Can't afford to keep buying new products every time an influencer recommends something

How Aluvi helps:

Aluvi takes her existing products, organizes them into a clear AM/PM order, and tells her what not to combine. She gets a routine she can actually follow — without buying anything new.

Persona 02 — Maya, 31 · "The Informed Overthinker"

• Location: Chicago
• Occupation: Marketing manager
• Skin type: Dry, early signs of aging
• Tags: Ingredient-aware · Reddit power user · Anti-aging focus

Background:

Maya has been into skincare for 3+ years. She reads r/SkincareAddiction regularly and knows the difference between AHA, BHA, and PHAs. She has a well-curated product shelf but second-guesses her routine constantly — "Am I using retinol too often? Should vitamin C go before or after moisturizer?"

Goals:

• Confirm her current routine is safe and optimized
• Get confidence around active ingredient scheduling (retinol on alternating nights, etc.)
• Understand the "why" behind each step

Frustrations:

• Information overload from conflicting Reddit advice
• Spends too much time validating routine decisions she should already be confident about
• Doesn't want a dumbed-down app — she wants substance

How Aluvi helps:

Aluvi validates her existing routine, flags any real conflicts, and gives her a structured schedule (which actives on which days). She gets clarity and confidence — not a lecture.

Persona 03 — James, 26 · "The Practical Minimalist"

• Location: Austin
• Occupation: Software engineer
• Skin type: Oily, occasional breakouts
• Tags: Complete beginner · Wants minimal steps · Efficiency-driven

Background:

James has never had a real skincare routine. He picked up a CeraVe cleanser and a moisturizer after a breakout last year, but he's not sure if he's using them correctly or if he needs anything else. He doesn't follow skincare content — he just wants to know what to do in the least number of steps.

Goals:

• A simple 3-step routine he can stick to every day
• Know if he actually needs sunscreen (he doesn't think he does)
• Not have to think about skincare more than 5 minutes a day

Frustrations:

• Everything online feels either too basic ("just wash your face") or too complex (10-step routines)
• Doesn't want to spend a lot of money on something he's not sure about
• Skeptical of beauty apps that feel too "girly" or overly aesthetic

How Aluvi helps:

Aluvi builds him the simplest possible routine from what he already owns, explains why each step matters in plain language, and gently educates him on sunscreen. No overwhelm. No judgment.

Section 01 — Brand Alignment Summary

Microcopy rules (from brand guideline)

• Speak like a helpful friend
• Focus on benefits, not features
• Be specific and actionable
• Avoid jargon and complex words
• Always be supportive and positive

End of Section 01. Next: Section 02 — Goals, Success Metrics & Out of Scope.

Section 02 — Goals & Success Metrics

Product goals for MVP v1.0

Three goals, in priority order:

Goal 1 — Validate product-market fit Prove that users will complete the onboarding quiz, receive a routine, and find it useful enough to return. This is the core hypothesis Aluvi is testing with MVP.

Goal 2 — Establish the habit loop Get users to open the app and check their routine at least 3 times in the first 7 days. A skincare app only works if it becomes part of daily behavior.

Goal 3 — Generate early revenue signal Validate willingness to pay via freemium conversion and affiliate click-through, before committing to full feature build.

Success metrics

Primary metrics (go/no-go for v1.1 investment)

Secondary metrics (directional, inform v1.1 priorities)

North star metric

Routines completed per active user per week. This captures whether Aluvi is actually changing behavior — not just whether people downloaded the app.

Launch criteria (definition of "ready to ship")

All of the following must be true before MVP v1.0 goes to App Store submission:

• All Must Have features pass QA on iPhone 14 and iPhone 16 (minimum device targets)
• Onboarding quiz completes end-to-end without crash on iOS 16+
• AI routine generation returns result in ≤ 10 seconds on standard WiFi
• Paywall displays correctly and IAP (In-App Purchase) flow completes successfully
• Affiliate links open correctly in Safari / in-app browser
• App Store listing approved (screenshots, description, privacy policy)
• Analytics events firing correctly for all primary metric tracking
• Crash-free rate ≥ 99% on TestFlight with ≥ 50 internal testers

Section 02 — Scope

In scope — MVP v1.0

Out of scope — MVP v1.0

Subscription model

No free tier. User downloads the app and immediately enters a 7-day free trial with full feature access. On day 7, subscription auto-starts unless cancelled.

Pricing options presented at paywall:

Three subscription tiers. Final pricing TBD — pending ad campaign CPL and conversion data.

Pricing will be finalized after ad campaign data (current CPL and conversion signals from Meta campaign) is reviewed. Founding member pricing should be set before app launch announcement.

All features are available to all subscribers (no feature tiering):

The paywall is shown at first launch, before onboarding. User selects a plan (or starts free trial) before using the app. This is a hard paywall — there is no persistent free tier.

Section 02 — Assumptions & Risks

Key assumptions

1. Users are willing to manually input the products they own (no barcode scan in MVP).
2. Sign in with Apple / Google is sufficient — no email/password needed.
3. AI routine generation (via Anthropic API) returns results in ≤ 10 seconds under normal conditions.
4. US users are familiar enough with Sephora and Amazon affiliate links to convert.
5. A hard paywall with 7-day free trial will not significantly suppress install-to-onboarding completion, as the trial provides full access with no upfront charge.

Risks

End of Section 02. Next: Section 03 — Feature Specifications & User Stories.

Section 03 — Feature Specifications & User Stories

How to read this section

Each feature is written as a user story in the format:

"As a [user], I want to [action], so that [outcome]."

Each story includes acceptance criteria — the specific conditions that must be true for the feature to be considered done. These are the dev handoff checkpoints.

Feature 01 — Authentication (Sign in with Apple)

User story:

As a new user, I want to sign in with Apple so that I can create an account quickly without a password.

Acceptance criteria:

• Sign in with Apple is the only authentication option
• No email/password, no Google sign-in
• On successful auth (first launch), user is directed to onboarding quiz
• On successful auth (returning user), user is directed to home screen
• User's name from Apple is used to personalize the greeting ("Good morning, Sarah")
• Auth token is stored securely in iOS Keychain
• If sign-in fails, a clear error message is shown: "Something went wrong. Please try again."
• Returning users are auto-signed in on app reopen (no re-auth required unless token expires)

Feature 02 — Paywall & Free Trial

User story:

As a new user who has just seen my personalized routine, I want to unlock full access so that I can keep using Aluvi beyond the trial.

Acceptance criteria:

• Paywall screen is shown after the user receives their first routine result — not before onboarding
• User flow: Sign in → Onboarding quiz → AI generation → Routine result (preview) → Paywall → Full access
• The routine result screen shows enough to demonstrate value (e.g. AM routine step 1–2 visible), then paywall appears to unlock the full routine
• Screen clearly communicates: "7 days free, then [price]. Cancel anytime."
• Three subscription options are displayed: Weekly, Monthly, Annual
• Annual plan is visually highlighted as "Best value"
• Founding member pricing is shown if user is in the pre-launch cohort (flag set server-side)
• "Start free trial" CTA is the primary action — one tap to begin
• Tapping any plan shows the native iOS subscription confirmation sheet (StoreKit)
• Trial start date and auto-renewal date are shown before confirmation
• On trial start, user is returned to their full routine result immediately
• If user dismisses paywall without subscribing, app closes (hard paywall — no bypass)
• Subscription state is validated on every app launch via StoreKit
• Expired or cancelled subscriptions redirect to paywall on next open

StoreKit notes for dev:

• Use StoreKit 2 (iOS 15+)
• Product IDs to be configured in App Store Connect before build: com.aluvi.weekly, com.aluvi.monthly, com.aluvi.annual, com.aluvi.founding
• Handle Transaction.currentEntitlements to validate active subscription on launch
• Restore purchases button must be accessible (App Store guideline requirement)

Feature 03 — Onboarding Quiz

User story:

As a new user, I want to answer a few quick questions about my skin and scan the products I already own, so that Aluvi can build a routine that's actually right for me.

Quiz structure (7 questions):

Q6 — Product input spec (barcode scan + fallback)

This is the most technically complex question in the quiz. It uses a dual-input approach.

Primary flow — barcode scan:

1. User taps "Scan a product" → camera opens (AVFoundation / native iOS camera)
2. User points camera at product barcode
3. App sends barcode to Open Beauty Facts API: GET https://world.openbeautyfacts.org/api/v2/product/{barcode}.json
4. If product found → product name + brand appears as a chip: "CeraVe Moisturizing Cream ✓"
5. User can scan another product (loop until done)
6. User taps "Done scanning" to proceed

Fallback flow — free text:

• If camera permission denied → show text input only, no scan option
• If product barcode not found in Open Beauty Facts → show message: "We couldn't find that product. Type the name instead." → free text field appears
• Free text input also always available alongside scan (user can mix both)

Product data handling:

• If barcode matched in Open Beauty Facts → store: { name, brand, barcode, ingredients[], source: "openbeautyfacts" }
• If free text only → store: { name, source: "user_input" } — AI will infer ingredient profile from product name
• If product name is unrecognizable (e.g. gibberish or clearly fake) → AI skips that product when generating routine. A notice is shown on Screen 11 (Routine Result) listing the skipped products — see Screen 11 spec for display details
• Maximum 10 products per quiz (UX limit — more than 10 is overwhelming)

Open Beauty Facts integration notes for dev:

• SDK: use official Swift SDK — openfoodfacts/openfoodfacts-swift on GitHub
• Required HTTP header on all API calls: User-Agent: Aluvi/1.0 (iOS; contact@aluviapp.com)
• Terms: 1 API call = 1 real user scan. No batch scraping. License: ODbL (attribution required in app's data/legal page)
• API is free, no rate limit for this use case
• Handle 404 (product not found) and timeout (>5s) gracefully with fallback to free text

Acceptance criteria:

• Each question occupies its own screen (one question per screen)
• Progress indicator visible at top (e.g. "3 of 7")
• User can go back to previous question without losing answers
• Q6: camera opens on tap of "Scan a product" button
• Q6: barcode detected within 2 seconds of pointing at product under normal lighting
• Q6: successful scan shows product name as a chip with green checkmark
• Q6: user can scan multiple products sequentially without leaving the screen
• Q6: user can manually remove a scanned product (tap × on chip)
• Q6: free text input is always available as alternative or supplement to scan
• Q6: unrecognized barcodes fall back to free text gracefully — no crash, no blocking error
• Q6: camera permission prompt uses clear copy: "Aluvi needs camera access to scan your products"
• Q6: if camera permission denied, scan button is hidden and only text input is shown
• All 7 questions must be answered before proceeding (Q6 requires at least 1 product)
• Answers are saved locally and sent to AI generation endpoint on quiz completion
• If user force-quits mid-quiz, progress is saved and quiz resumes from last answered question
• Quiz completion triggers transition to AI loading screen

Feature 04 — AI Routine Generator

User story:

As a user who has completed the quiz, I want to receive a personalized AM and PM routine so that I know exactly what to use and in what order every day.

How it works: Quiz answers are sent to the Anthropic API. The prompt instructs Claude to generate a structured AM/PM routine based on the user's skin type, concerns, products owned, budget, and goals. The response is parsed into a structured routine object and displayed on the routine screen.

Acceptance criteria:

• AI generation begins immediately after quiz completion
• Loading screen is shown during generation with reassuring microcopy (e.g. "Analyzing your skin data…")
• Generation completes in ≤ 10 seconds on standard WiFi. If > 10 seconds, a secondary message appears: "Almost there…"
• If generation fails (API error / timeout), user sees an error screen with a "Try again" button — quiz answers are preserved
• Routine output includes: product name, step number, brief usage instruction (1–2 sentences), and AM/PM designation
• Products the user already owns are prioritized in the routine
• If a product the user owns creates an ingredient conflict, it is flagged (see Feature 06)
• Recommended new products (with affiliate links) are shown separately below the routine — not mixed into the core routine steps
• Routine is structured as: AM routine (ordered list) + PM routine (ordered list)
• Each step shows: step number, product name, product type (e.g. "Cleanser"), brief instruction
• Routine is automatically saved to the user's account on generation

AI prompt requirements (for backend / prompt engineering):

• Output must be structured JSON parseable by the iOS client
• Output schema:

{
  "personalized_intro": "string",
  "am": [{ "step": "", "product": "", "type": "", "instruction": "" }],
  "pm": [{ "step": "", "product": "", "type": "", "instruction": "" }],
  "conflicts": [{ "product_a": "", "product_b": "", "reason": "", "fix": "" }],
  "recommendations": [{ "product": "", "reason": "", "affiliate_url": "" }]
}

• Prompt must enforce: cosmetic-only recommendations, no medical claims, no diagnosis language
• Routine should default to simplicity — 4–5 steps per session unless user's product list justifies more

Personalized intro block

personalized_intro is a 2–3 sentence block written based on the combination of the user's Q2 (skin concerns), Q3 (sensitivity), and Q7 (primary goal) answers. This block appears on the routine result screen before the paywall, beneath the main headline.

Prompt instructions for personalized_intro

• Write in second person ("your skin", "you") — not like a brand, but like a knowledgeable friend who understands the user's situation
• Never mention age, never use medical language, never use fear or scare tactics
• Must reflect one specific insight about the user's concern + goal combination — so it feels like Aluvi genuinely understands their situation, not a generic template
• Close with a sentence that connects back to the routine that was just built — reinforcing that this routine was made specifically for them
• Maximum 60 words
• Tone: warm, grounded, quietly reassuring — not hypey, not judgmental

Example outputs per concern combination

Anti-aging + sensitive skin + goal: anti-aging

"Skin that's starting to change in texture and elasticity needs a different approach — not more products, but the right ones in the right order. A lot of people over-layer at this stage and end up with skin that's more reactive, not better. This routine is designed to be simple but targeted, built around exactly what your skin needs right now."

Acne + not sensitive + goal: clear skin

"Your skin actually has more capacity to recover than you might think. The problem is almost never the products themselves — it's the order they're used in, and when. This routine fixes that, so nothing you already own is working against you."

Dryness + very sensitive + goal: hydration

"Skin that stays dry even with moisturizer almost always has one root cause: products applied in the wrong order, so the active ingredients never fully absorb. This routine corrects that sequence — and accounts for how easily your skin reacts."

Oiliness + not sensitive + goal: clear skin

"Oily skin that keeps breaking out despite a full routine is often actually under-hydrated, not over-producing oil. This routine is built to rebalance that — not just suppress sebum."

Multiple concerns + very sensitive + goal: simpler routine

"With skin that reacts easily, less is almost always more. This routine removes the steps that aren't earning their place and keeps only what genuinely works for your skin — no unnecessary experimentation."

Feature 05 — Routine Screen (Home)

User story:

As a returning user, I want to see my routine clearly on the home screen so that I know exactly what to do this morning or tonight.

Acceptance criteria:

• Home screen shows today's AM or PM routine depending on time of day (AM default before 12pm, PM after)
• User can toggle between AM and PM manually
• Each step is shown as a tappable list item with product name, type, and instruction
• Tapping a step expands it to show full usage details and ingredient notes (premium feature)
• Each step has a "Mark as done" checkbox — completing all steps triggers a positive feedback moment (animation + message)
• Progress bar shows how many steps are completed today
• Header shows personalized greeting: "Good morning, [name]" with current streak
• "Edit routine" or "Refresh routine" CTA is accessible from this screen
• Bottom navigation: Home · Routine · Progress · Profile

Feature 06 — Ingredient Conflict Notice

User story:

As a user with potentially conflicting active ingredients, I want to know that Aluvi has spotted the issue and already sorted it out, so I can use my products safely without having to figure it out myself.

How it works:

• Conflict detection runs automatically as part of AI routine generation
• If a conflict is detected, AI incorporates a safe alternating schedule directly into the routine — the fix is baked into the routine steps, not a separate action required from the user
• A one-time informational notice is shown on Screen 11 (Routine result preview) after generation, reassuring the user that the conflict has been handled
• The notice is not a warning — it is a trust signal: "We spotted something and already built your schedule around it"
• No persistent alert, no badge, no separate action required from user
• If no conflict is detected, nothing is shown — silence is the signal

Acceptance criteria:

• Conflict detection runs as part of AI routine generation
• If conflict detected, AI adjusts the routine schedule to safely alternate conflicting products — this is reflected in the step instructions
• A one-time informational notice is shown on Screen 11 if a conflict was detected and handled — see Screen 11 spec for display details
• Notice is shown once only — not persistent, not shown again after user continues to Screen 13
• No conflict badge on bottom nav, no persistent banner on Screen 13
• No conflict = nothing shown. Do not show "no conflicts found" message
• Conflict data is included in the AI JSON output and rendered client-side
• Screen 14 remains accessible from Screen 11 notice as an optional detail view — not a required step

Feature 07 — Product Recommendations

User story:

As a user whose current products have gaps, I want to see what to add to my routine so that I can complete it without spending more than my budget.

How it works — curated catalog approach:

Recommendations are not generated ad-hoc from the web. They are pulled from a pre-built internal catalog of 200–300 curated US skincare products. Claude selects the best matches from this catalog based on the user's skin type, concerns, budget, and routine gaps.

Catalog build process (pre-launch, one-time):

1. Use Claude to define top 200–300 skincare products by category (cleanser, moisturizer, serum, SPF, toner, retinol, AHA/BHA, eye cream) — prioritize products popular in US market
2. Use Openclaw to scrape product details + direct URLs from Sephora and Amazon
3. Claude structures output into JSON catalog per product using agreed schema
4. Cross-reference with Open Beauty Facts for ingredient enrichment where available
5. Store in Supabase/Postgres as the recommendation database
6. Update catalog quarterly (or when major products launch/discontinue)

Catalog testing findings (April 24, 2026): Initial scrape of 36 products completed using Openclaw. Key findings:

• Sephora data quality is strong — skin_type_fit, concerns, ingredients, and sephora_url all populated correctly
• Amazon data is sparse — skin_type_fit, concerns, and ingredients all empty due to generic listing format
• Amazon product names are too long (raw listing titles) — need cleaning before use in UI
• notes field is auto-generated and generic — needs rewrite per product before launch
• AHA/BHA category has 0 products — critical gap, must be filled before launch

Required fixes before launch:

• Enrich Amazon products — use Claude to fill skin_type_fit, concerns, and clean name for all 16 Amazon products
• Rewrite notes field for all 36 products using Claude — 1 natural sentence per product
• Add AHA/BHA category — minimum 5–6 products (e.g. The Ordinary AHA 30%, Paula's Choice BHA 2%)
• Add moisturizer products — currently only 3, target 8–10
• Add serum products — currently only 3, target 8–10
• Fill affiliate_tag for all products after Amazon Associates + Sephora affiliate accounts are approved

Catalog schema per product:

{
  id, name, brand, category,
  skin_type_fit: [],     // e.g. ["oily", "combination"]
  concerns: [],          // e.g. ["acne", "brightening"]
  price_usd: number,
  price_tier: "budget" | "mid" | "premium",
  sephora_url: string,   // direct product page
  amazon_url: string,    // direct product page
  affiliate_tag: string,
  ingredients: [],       // from Open Beauty Facts if available
  notes: string          // 1-sentence "why this works" — written manually or AI-generated
}

Recommendation logic:

• Claude receives user's skin profile + current products + quiz answers
• Claude queries catalog (passed as context) and selects 2–3 products that fill routine gaps
• Budget filter: only recommend products within user's stated price tier (Q4)
• Exclude products the user already owns (matched by name or barcode)
• Prioritize products with both Sephora and Amazon URLs for flexibility

Acceptance criteria:

• Recommendations section is labelled "You might also need" — shown below routine result
• Maximum 3 recommendations shown (avoid overwhelming)
• Each recommendation shows: product image (from catalog), name, brand, 1-sentence reason, price, and CTA button ("View on Sephora" or "View on Amazon")
• Recommendations respect user's budget tier from Q4
• Products the user already scanned/entered are never recommended
• Affiliate links are direct product page URLs (not search pages)
• Links open in SFSafariViewController (in-app browser)
• Affiliate link taps are tracked as analytics events: recommendation_tapped { product_id, source }
• If routine is complete with no gaps, recommendations section is NOT hidden — instead show a positive completion state: "You're all set. Your current products are everything you need for this routine." No CTA, no upsell, no product shown.
• Tone of recommendations must feel like a friend suggesting, not a store pushing. Copy: "You might also like..." not "Complete your routine with..." or "Upgrade your routine."
• Never show more than 3 recommendations regardless of how many gaps exist
• Recommendations section label: "One thing that might help" (singular framing feels less pushy than a list)
• No urgency language anywhere in this section — no "limited", "popular", "trending", "best seller" labels
• Catalog must contain minimum 50 products at launch across all major categories

Feature 08 — Save & Share Routine

User story:

As a user who loves my routine, I want to save it and share it so that I can reference it anytime and show friends.

Acceptance criteria:

• Routine is auto-saved to the user's account on generation (no manual save required)
• User can access saved routine from the Routine tab at any time
• Share button generates a clean image card of the routine (AM + PM steps, Aluvi branding)
• Share sheet uses native iOS UIActivityViewController
• Shared image includes Aluvi logo and "aluviapp.com" as attribution
• Share does not expose personal quiz answers — only the routine steps

Feature 09 — Progress Tracking

User story:

As a consistent user, I want to track my daily routine completion so that I can see my streak and stay motivated.

Acceptance criteria:

• Each day a user completes all steps in AM or PM routine, a completion is logged
• Current streak is shown on home screen header
• Progress screen shows: current streak, weekly completion chart (7-day bar), total days completed
• Completing a full routine (all steps checked) triggers a positive feedback animation + message
• Streak resets if user misses a full day (no completion logged)
• Data is stored in user's account (not local only) so it persists across device changes

Feature 10 — Add Product to Routine

User story:

As a returning user who bought a new product, I want to add it to my routine without retaking the full quiz, so that Aluvi can update my routine to include it.

How it works:

• Accessible from Screen 13 (Full routine result) via an "Edit products" CTA
• User scans barcode or enters product name manually — same dual-input flow as Q6 in the onboarding quiz
• After adding, user taps "Update routine" CTA to trigger re-generation
• AI receives: existing quiz answers (stored) + existing product list + newly added product(s)
• Routine is re-generated in full — same AI generation flow as initial quiz
• Loading screen (Screen 10) is shown during re-generation
• Updated routine replaces the previous routine on completion

Entry point: Screen 13 (Full routine result) → "Edit products" CTA

Exit points:

• "Update routine" tapped → AI loading screen → Updated routine result (Screen 13)
• Cancelled → back to Screen 13, no changes

Key UI elements:

• "Edit products" CTA — accessible from Screen 13, positioned below the routine steps list
• Product input sheet (bottom sheet modal): same barcode scan + free text fallback as Q6
• Added product appears as chip in the sheet — user can add multiple before confirming
• "Update routine" primary CTA — triggers re-generation
• "Cancel" link — dismisses sheet, no changes

States:

• Default: empty input, "Update routine" CTA disabled
• Product added: chip(s) visible, "Update routine" CTA enabled
• Loading: AI re-generation in progress (Screen 10)
• Success: updated routine shown on Screen 13

Notes:

• Quiz answers (Q1–Q5, Q7) are never re-asked — they are stored and reused as-is
• Existing product list is preserved; new products are appended and removed products are excluded
• If the new product is unrecognized by AI → same behavior as initial quiz: skipped silently, notice shown on result screen
• Re-generation uses identical AI prompt as initial routine generation — no special handling needed
• "Update routine" tap is the only trigger for re-generation — no auto-update on product add
• Streak is preserved after routine re-generation — editing products is not a break in habit. Streak only resets if user misses a full day with no routine completion logged.

Acceptance criteria:

• "Edit products" button (+ Edit products) is visible on Screen 13 (Full routine result) for active subscribers, inline below the routine steps list
• Tapping "Edit products" opens Screen 17 bottom sheet
• Bottom sheet pre-loads all existing products (from Q6) as removable chips on open
• User can remove existing product chips — removed products are excluded from re-generation
• "Update routine" CTA is enabled by default (existing products present); disabled only if all chips are removed
• Bottom sheet camera uses same Open Beauty Facts barcode scan flow as Q6
• User can add multiple new products before tapping "Update routine"
• New product chips appear alongside existing chips — no visual distinction
• Tapping "Update routine" triggers AI loading screen (Screen 10)
• AI receives the final chip list as the complete product list
• Updated routine replaces previous routine on completion
• If user cancels without updating, existing routine and product list are unchanged
• Analytics event fired on update: routine_updated { user_id, products_added: n, products_removed: n }

End of Section 03. Next: Section 04 — UX Flows & Screen Structure.

Section 04 — UX Flows & Screen Structure

How to read this section

Each screen is documented with:

• Purpose — what this screen exists to do (one job only)
• Entry point — what triggers navigation to this screen
• Exit points — where the user can go from this screen
• Key UI elements — components that must be present
• States — all possible states the screen can be in
• Notes — UX decisions and rationale

Master user flow

App launch
  └── Returning user (has active subscription)
        └── Home screen
  └── New user / logged out
        └── Welcome screen
              └── Sign in with Apple
                    └── [First time] Onboarding quiz
                          └── Q1 → Q2 → Q3 → Q4 → Q5 → Q6 (scan) → Q7
                                └── AI loading screen
                                      └── Routine result (preview)
                                            └── Paywall
                                                  └── [Subscribed] Full routine result
                                                        └── Home screen
                                                  └── [Dismissed] App closes
                    └── [Returning, active sub] Home screen
                    └── [Returning, expired sub] Paywall

Screen 01 — Splash / App launch

Purpose: Brand moment. Check auth + subscription state. Route user to correct destination.

Entry point: App opens

Exit points:

• Active subscriber → Home screen (auto, no interaction)
• New / logged out → Welcome screen (auto)
• Expired subscription → Paywall

Key UI elements:

• Aluvi logo centered
• Warm White background (#FAFAF8)
• No buttons, no text other than logo

States:

• Default: logo visible, checking auth in background
• Duration: max 2 seconds before routing

Notes:

• No loading spinner — keep it clean
• Auth check and subscription validation happen silently here

Screen 02 — Welcome screen

Purpose: First impression. One job: get user to sign in.

Entry point: New user or logged-out user after splash

Exit points:

• Sign in with Apple → success → Onboarding quiz (new) or Home (returning)

Key UI elements:

• Aluvi logo + wordmark
• Hero headline (H1)
• Supporting subtext (Body 1)
• "Continue with Apple" button (primary, full width)
• Legal footnote: "By continuing, you agree to our Terms and Privacy Policy"

States:

• Default
• Loading (after Apple tap, waiting for auth response)
• Error (auth failed — show inline message, keep button active)

Notes:

• No "Sign up" vs "Log in" distinction — Apple handles both in one flow
• Keep copy minimal — this is not a sales page, the landing page already did that job

Screen 03–09 — Onboarding quiz (Q1–Q7)

Each question is a separate screen. Shared layout across all 7 screens.

Purpose: Collect the data needed to generate a personalized routine.

Entry point: First sign-in (new user only). Never shown again after completion.

Exit points:

• "Next" → next question
• Back chevron → previous question
• Q7 "Done" → AI loading screen

Shared UI elements (all quiz screens):

• Progress bar at top (e.g. step 3 of 7) — Aluvi Green fill
• Back chevron (top left) — except Q1 where back returns to Welcome
• Question text (H1)
• Supporting hint text (Body 2, muted) where needed
• Answer options (tappable cards or chips)
• "Next" CTA button (primary, sticky bottom) — disabled until selection made
• Q7 uses "Build my routine →" instead of "Next"

Per-screen specifics:

Q1 — Skin type

• Input: single select, 5 options as large tappable cards with icon
• Options: Dry · Oily · Combination · Normal · Sensitive
• Hint: "Not sure? Choose Combination if your T-zone gets oily."

Q2 — Skin concerns

• Input: multi-select chips, max 3 selections
• Options: Acne · Dark spots · Anti-aging · Dryness · Oiliness · Redness · Uneven texture · Brightening
• Counter shows: "1 of 3 selected" — turns to "3 of 3 — that's enough!" at max
• Hint: "Pick up to 3. Focus on what bothers you most."

Q3 — Skin sensitivity

• Input: single select, 3 options
• Options: Not sensitive · Mildly sensitive · Very sensitive
• Hint: "Sensitive skin reacts easily to new products or strong actives."

Q4 — Budget

• Input: single select, 4 options
• Options: Under $20 · $20–$50 · $50–$100 · $100+
• Hint: "This helps us recommend products you'll actually buy."
• Note: this is monthly skincare spend, not per-product

Q5 — Sunscreen habit

• Input: single select, 3 options
• Options: Yes, every day · Sometimes · No, not really
• No hint — question is self-explanatory
• Note: answer informs whether SPF is added to AM routine or gently introduced

Q6 — Products owned (barcode scan + text)

• This screen is different from Q1–Q5. See Feature 03 spec for full detail.
• Key UI: camera viewfinder area (top 60% of screen) + scanned product chips below + "Add manually" text link + "Done" CTA
• States:
  • Default: camera active, no products scanned yet. CTA disabled.
  • Scanning: brief flash/highlight on successful scan
  • Product added: chip appears below viewfinder with product name + × to remove
  • Not found: inline message below viewfinder: "Product not found — type the name instead"
  • Camera denied: viewfinder replaced with text input field
  • Min 1 product required to enable "Done" CTA
• Hint at top: "Scan the barcode on each product you own. We'll build your routine around what you already have."

Q7 — Primary skin goal

• Input: single select, 5 options as tappable cards
• Options: Clear skin · Even tone · Anti-aging · Hydration · Simpler routine
• No hint
• CTA: "Build my routine →" (not "Next")
• This is the emotional peak of the quiz — copy and interaction should feel like a commitment

Wireframe — Quiz screens Q1–Q5, Q7 (single/multi-select template, showing Q2):

Wireframe — Q6 (product scan, dual input):

Screen 10 — AI loading screen

Purpose: Manage expectation during AI generation (up to 10 seconds). Maintain excitement, not anxiety.

Entry point: Q7 completed

Exit points:

• Generation complete → Routine result screen (auto)
• Generation failed → Error state with "Try again" button

Key UI elements:

• Centered Aluvi spark icon (animated — gentle pulse)
• Rotating microcopy messages (swap every 2.5s):
  • "Analyzing your skin profile…"
  • "Checking your products for conflicts…"
  • "Building your morning routine…"
  • "Putting together your evening routine…"
  • "Almost ready…" (shown after 7s if still loading)
• No progress bar — duration is unpredictable, a stuck progress bar causes anxiety

States:

• Loading (default)
• Long load (>7s): swap to "Almost ready…" message
• Error (API fail / timeout >15s): show "Something went wrong. Your answers are saved — tap to try again." with retry button

Notes:

• Never show a blank screen — even on error, keep the calm visual
• Quiz answers must be preserved in local storage before this screen loads

Screen 11 — Routine result (preview + paywall gate)

Purpose: Show enough of the routine to demonstrate clear value, then present paywall.

Entry point: AI loading complete

Exit points:

• "Start free trial" → Paywall → Full routine
• Paywall dismissed → App closes

Key UI elements:

• Personalized headline using first name from Apple sign-in (H1): "[Name], your routine is ready." — e.g. "Sarah, your routine is ready."
• Fallback if Apple returns no name: display "Your routine is ready." — do not show a blank or "[Name]" placeholder
• Dev note: Apple may return empty name if user selects "Hide My Email" or has no name set on Apple ID. Always check for nil/empty before rendering name.
• [NEW] Personalized intro block: output from personalized_intro field in the AI response — displayed below the subtext, before the AM routine preview. Body text, no card or container. Max 60 words; truncate at last complete sentence within limit. If empty or API error, element is not shown — no placeholder, no error state.
• Unrecognized product notice: if AI skipped one or more products during generation, show an inline notice below the personalized intro block (above AM routine preview). Format: "We couldn't identify [product name] — it wasn't included in your routine." One line per skipped product. Muted text style, no icon, no error state — informational only. If no products were skipped, this element is not shown.
• Conflict notice (if conflicts detected) — informational only, not an alert. One-time, shown on this screen only. Reassurance tone: AI has already built a safe schedule. Tappable to open Screen 14 for detail. Not shown on Screen 13 or anywhere else after this.
• Sticky bottom sheet: paywall CTA — "Unlock your full routine — 7 days free"

Element order:

1. Personalized headline: "[Name], your routine is ready."
2. Subtext: "Built around your products. Personalized for your skin."
3. [NEW] Personalized intro block
4. [NEW] Unrecognized product notice (if applicable)
5. Conflict notice (if applicable) — informational, one-time
6. AM routine preview (first 2 steps visible, remaining steps blurred)
7. Sticky bottom sheet: paywall CTA

States:

• Default: preview visible, paywall bottom sheet present
• No "skip" or "later" — hard gate

Notes:

• Show real content in the preview (step 1 and 2 of AM routine) — not a mockup
• Conflict notice on this screen is intentional — it signals Aluvi has already done the thinking for the user, increasing trust and conversion
• Do not blur the product names in preview — user should recognize their own products to feel the personalization

Screen 12 — Paywall

Purpose: Convert trial. Present 3 plan options clearly. Remove friction.

Entry point: Routine result preview (first time), or expired subscription

Exit points:

• Plan selected + confirmed → StoreKit sheet → success → Full routine result
• Dismissed (X button or swipe) → App closes (hard paywall)

Key UI elements:

• Brief value recap (2 lines max): "Your personalized AM & PM routine, built around your products."
• 3 plan cards: Weekly · Monthly · Annual
• Annual card visually highlighted: "Best value" badge
• Founding member card: shown only if pre-launch cohort flag is true
• "Start free trial" primary CTA (maps to selected plan)
• Fine print: "7 days free, then [price]. Cancel anytime in Settings."
• Restore purchases link (required by App Store)

States:

• Default: Annual pre-selected
• Plan selected: selected card highlighted in Aluvi Green
• Loading: after tap, show spinner while StoreKit initializes
• Success: brief success animation → route to full routine
• Error: StoreKit error → show "Purchase failed. Please try again." inline

Notes:

• No feature comparison table — keep it simple, not a feature matrix
• Founding member pricing is a separate card, not a toggle
• Annual plan pre-selected by default to anchor perception

Screen 13 — Full routine result

Purpose: Deliver the full value. This is the "wow" moment.

Entry point: Paywall completed (first time) or Home → Routine tab

Exit points:

• Step detail → expand inline (no new screen)
• Product recommendation card → opens Sephora or Amazon in in-app browser (SFSafariViewController)
• Home tab → Home screen
• Share → iOS share sheet

Key UI elements:

• AM / PM toggle (top)
• Recommendations section — always visible directly below the AM/PM toggle, above the routine steps list
• Routine steps as ordered list — each step: number, product name, type, brief instruction
• Conflict notice entry point — if the routine has ingredient conflicts, a subtle tappable row is shown at the bottom of the routine steps list (above the "+ Edit products" button). Format: "Some products in this routine are scheduled to avoid clashes. See details →". Tapping opens Screen 14.
• "+ Edit products" button — inline, below the routine steps list. Icon + label. Secondary style (not primary/filled — should not compete with "Start routine"). Tapping opens Screen 17 (Edit products bottom sheet).
• Share button (top right)
• Sticky bottom CTA: "Start routine" → marks steps as in-progress

Screen 13 content order (top to bottom):

1. AM / PM toggle
2. Recommendations section
3. Routine steps list
4. Conflict notice entry point (if applicable)
5. "+ Edit products" button (inline, below steps)
6. Sticky bottom CTA: "Start routine"

Notes:

• Conflict notice on Screen 13 is a permanent, low-key entry point — not a warning, just an informational link for users who want to understand their schedule
• Replaces the old note that Screen 14 was only accessible from Screen 11

States:

• AM view (default before 12pm)
• PM view (default after 12pm)
• Step expanded: tapping a step shows full usage instruction inline
• Step completed: checkbox ticked, step grays out with strikethrough
• All steps done: celebration moment — green checkmark animation + "Great job! Routine complete."

Recommendations section — display conditions:

Recommendations are always visible on this screen, directly below the AM/PM toggle and above the routine steps. They are not triggered by step completion — they are the first content-level element the user sees after the toggle. This maximises affiliate exposure while the user is most engaged. Display logic is determined by routine gaps detected during AI generation:

This means:

• Recommendations are visible from the first time the user opens their routine, not after completing steps
• The section is always present (never hidden) — it either shows product cards or the completion state
• Max 3 product cards regardless of how many gaps exist
• Products always respect user's budget tier (Q4 answer)
• Products the user already owns are never shown

Screen 14 — Ingredient conflict detail

Purpose: Let users understand the conflict Aluvi detected and how the routine already handles it. Informational only — no action required.

Entry point:

• Tap on conflict notice on Screen 11 (Routine result preview — first time)
• Tap on conflict notice entry point on Screen 13 (Full routine — permanent access post-subscribe)

Exit points:

• Back → Screen 11 or Screen 13 (depending on entry)
• "Got it" → Screen 11 or Screen 13 (depending on entry)

Key UI elements:

• Conflict summary: "[Product A] + [Product B]"
• Plain-language explanation (2–3 sentences max) — what the potential conflict is and why it matters
• "Here's what we did" section — shows the safe alternating schedule AI already built into the routine (e.g. "Retinol on Mon · Wed · Fri, AHA on Tue · Thu")
• "Got it" CTA (primary)

Notes:

• No severity badge — framing is not about danger level, it's about the solution
• Tone: smart friend who already sorted it out, explaining what they did and why
• No action required from user — the schedule is already in the routine

Screen 15 — Progress screen

Purpose: Show consistency and motivate the habit loop.

Entry point: Bottom nav → Progress tab

Exit points:

• Back to any tab via bottom nav

Key UI elements:

• Current streak (large, prominent)
• 7-day completion chart (bar chart, Aluvi Green)
• Total days completed (since account creation)
• Motivational microcopy tied to streak (see copywriting section)
• Skin improvement indicators (if 14+ days data available): Oil control · Pores · Brightness · Acne — each showing "Improving / Stable"

States:

• Empty (day 1, no data): "Start your first routine today. Your progress will show here."
• Active (has streak): full view
• Streak broken: gentle message — "You missed a day — no worries. Start fresh today."

Screen 16 — Profile / Settings

Purpose: Account management. Minimal — not a feature dump.

Entry point: Bottom nav → Profile tab

Key UI elements:

• User avatar (tappable) + user name — avatar tap opens photo picker sheet (see below)
• Subscription status + renewal date
• "Manage subscription" → opens iOS subscription management (external)
• "Retake quiz" → restarts onboarding, generates new routine
• "Restore purchases" (required)
• App version
• Links: Privacy Policy · Terms of Use · Data sources (Open Beauty Facts attribution — required by ODbL license)

Avatar / photo profile sheet: Tapping the avatar opens a bottom sheet modal with two options:

• "Take photo" → opens native iOS camera (UIImagePickerController, camera source)
• "Choose from library" → opens native iOS photo library (UIImagePickerController, photo library source)
• "Cancel" link — dismisses sheet Photo is cropped to a circle on selection (1:1 ratio, center crop). Stored in Supabase storage per user account. Replaces the Apple ID avatar on the profile screen only — does not affect Apple ID.

States:

• Active subscriber: shows plan name + next renewal date
• Trial: shows "Trial ends [date]"
• Expired: shows "Subscription ended" + "Renew" CTA → Paywall
• Avatar not set: shows initials from Apple ID name as placeholder (e.g. "A" for Ardho)

Bottom navigation structure

Present on all post-onboarding screens. (Screens 13–16)

Notes:

• 4 tabs maximum — consistent with brand principle of reducing decision fatigue
• Active tab uses Aluvi Green

Screen 17 — Edit products (bottom sheet)

Purpose: Let returning users add new products to their existing routine without retaking the full quiz.

Entry point: Screen 13 (Full routine result) → "Edit products" CTA

Exit points:

• "Update routine" tapped → AI loading screen (Screen 10) → updated Screen 13
• "Cancel" or swipe to dismiss → Screen 13, no changes

Key UI elements:

• Bottom sheet modal (not a full screen)
• Camera viewfinder (top portion of sheet) for barcode scan — same as Q6
• Existing product chips — all products from the user's quiz (Q6) are pre-loaded as chips below the viewfinder, each with × to remove. These are editable — user can remove an existing product from here, and it will be excluded from the re-generated routine
• New scanned/typed products also appear as chips in the same area, visually identical to existing chips
• "Add manually" text link — opens text field inline
• "Update routine" primary CTA — enabled by default (existing products already present); disabled only if all chips are removed
• "Cancel" link (top left of sheet)

States:

• Default: camera active, all existing products shown as chips, "Update routine" enabled
• Product added: new chip appears alongside existing chips
• Product removed: chip disappears; if all chips removed, "Update routine" disabled with hint "Add at least one product"
• Not found: inline message "Product not found — type the name instead"
• Camera denied: viewfinder replaced with text input only

Notes:

• Sheet dismisses on "Cancel" or background tap — no changes saved
• After "Update routine" is tapped, sheet dismisses and Screen 10 (loading) is shown
• AI receives the final chip list as the complete product list — existing chips that were removed are excluded from re-generation
• Same barcode + free text logic as Q6 — no new dev work beyond reusing the component
• No visual distinction between existing and new product chips — they are treated equally

Screen 18 — Home

Purpose: Single entry point for daily routine execution. User opens the app, knows exactly what to do right now, and starts. One job only.

Entry point:

• App launch (returning user with active subscription)
• Bottom nav → Home tab
• After completing paywall (first time)

Exit points:

• "Start routine" / "Continue routine" CTA → Screen 13 (Full routine result)
• Tapping weekly calendar strip → Screen 15 (Progress)
• Bottom nav → Routine · Progress · Profile tabs

Key UI elements:

• Greeting header— time-based personal greeting (H1)

• Before 12pm: "Good morning, [Name]"

  • After 12pm: "Good evening, [Name]"
  • Fallback (no name): "Good morning" / "Good evening"

• UV Index badge — displayed inline to the right of the greeting. Format: "UV [n] · wear SPF" — amber tone. Only shown when location permission is granted and UV data is available. If UV is 0–2 (low), badge is hidden. If location unavailable, badge is hidden — no error state shown. Tapping does nothing (informational only).

• Weekly calendar strip — 7-day horizontal strip showing M–S with completion status per day. Replaces streak badge. Each day shows: day letter, date number, and a filled green circle (done), outlined green circle (today, not yet done), or muted circle (missed/future). Tapping the strip navigates to Screen 15 (Progress). Shown below the greeting row.

• AM/PM toggle — manual toggle to switch between Morning and Evening routine view. Auto-defaults to AM before 12pm, PM after.

• Today's routine card— prominent card, auto-switched by time of day. Contains:

• Routine label: "Morning routine" / "Evening routine"

  • Step count + estimated time: "5 steps · ~3 min"
  • Progress bar: today's completion progress
  • First-step preview — shows Step 1 inline: step number circle, product type, product name, chevron. Gives user immediate context before tapping. Tapping the preview row navigates directly to Screen 13.
  • "Start routine" primary CTA

• Skin tip — one personalized tip per day, shown below the routine card. Rotates daily, derived from the user's skin profile (type + concerns from quiz). Label: "Today's tip". See copywriting section for format.

• Milestone banner — shown only on streak milestone days (day 7, 14, 30). Calm, not celebratory. Disappears after user starts their routine that day.

• Completion state — if all steps already done today, routine card shows completion message instead of CTA.

Screen element order (top to bottom):

1. Greeting + UV Index badge
2. Weekly calendar strip
3. AM/PM toggle
4. Today's routine card (with first-step preview)
5. Skin tip
6. Milestone banner (if applicable)

States:

• Routine not started today: default card, progress bar at 0, "Start routine" CTA, first-step preview visible
• Routine in progress: progress bar partially filled, CTA changes to "Continue routine"
• Routine complete today: completion message, no CTA — calm, not over-the-top
• Streak broken (missed yesterday): gentle notice below greeting — "You missed a day — no worries. Start fresh today." Disappears once user starts routine.
• Location permission denied: UV badge hidden — no error, no prompt. Screen functions normally.
• UV data unavailable (offline / API fail): UV badge hidden silently.

Notes:

• Home is intentionally minimal — no recommendations, no conflict info, no feed. Those live on Screen 13 and Screen 15.
• Weekly calendar strip replaces streak number badge — more visual, less gamified, same information density
• First-step preview makes the routine feel personal before user even taps — they recognize their own product immediately
• UV badge is a lightweight daily hook; SPF reminder is directly actionable within the routine
• AM/PM auto-switch threshold is 12pm — same as Screen 13

End of Section 04. Next: Section 05 — Copywriting Per Screen.

Section 05 — Copywriting Per Screen

Copywriting principles (from brand guideline)

Before reading the copy below, internalize these rules. Every line of copy in Aluvi must pass all five:

1. Speak like a smart friend — not a brand, not a doctor, not a salesperson
2. Focus on benefits, not features — "know exactly what to use" not "AI-powered routine generation"
3. Be specific and actionable — "Apply 2–3 drops to clean skin" not "Use as directed"
4. Avoid jargon — "conflicts" not "contraindicated actives", "morning" not "AM"
5. Always supportive and positive — even errors should feel calm, not alarming

Screen 01 — Splash

No copy. Logo only.

Screen 02 — Welcome screen

Rationale: Headline is benefit-first and punchy — mirrors the pain point ("guessing") and the payoff ("glowing") in 5 words. Subtext handles the "what is this" question before the user even asks.

Screen 03 — Q1 Skin type

Screen 04 — Q2 Skin concerns

Rationale: "What bothers you most" is more emotionally resonant than "What are your skin concerns" — it mirrors how users actually think and talk about their skin.

Screen 05 — Q3 Skin sensitivity

Rationale: Reframed from "How sensitive is your skin?" to "How does your skin react?" — more concrete and easier to self-assess. Options rewritten from technical labels to behavioral descriptions.

Screen 06 — Q4 Budget

Rationale: Hint reassures user this won't be used to upsell them. Addresses the implicit anxiety of "is this app going to tell me to spend $300?"

Screen 07 — Q5 Sunscreen habit

Rationale: "Honestly, not really" feels non-judgmental — it gives permission to be truthful. This matters because sunscreen data directly shapes the AM routine output.

Screen 08 — Q6 Products owned (scan)

Rationale: "We don't store photos" in the camera permission prompt is a trust builder — users are increasingly wary of apps accessing camera. Addressing it proactively reduces drop-off at this permission gate.

Screen 09 — Q7 Primary goal

Rationale: "Build my routine →" instead of "Next" — this is the commitment moment. The arrow signals forward momentum. "There's no wrong answer" removes performance anxiety at the final step.

Screen 10 — AI loading screen

Rotating messages, swap every 2.5 seconds:

Error state:

Rationale: Loading copy is active and specific — each message tells the user what's happening right now, not a generic "loading." Error message is honest and casual ("it usually works on the second go") — this reduces frustration by normalizing the hiccup.

Screen 11 — Routine result preview (pre-paywall)

Rationale: Conflict notice is reassurance-first — "we've already sorted it" not "warning: danger." User does not need to take any action; the schedule is already in their routine. Tapping is optional for those who want to understand the detail.

Screen 12 — Paywall

Microcopy below plans:

"No charge today. Cancel before day 7 and you won't be billed."

Rationale: "Your skin. Your routine." is the most personal possible headline for a paywall — it reframes the purchase as ownership, not a subscription. The microcopy "No charge today" directly addresses the #1 paywall anxiety and is proven to increase trial starts.

Screen 13 — Full routine result

Recommendations section copy:

Rationale: "You're all set" with zero CTA is a trust-building moment. It signals that Aluvi is not trying to sell — increasing long-term loyalty and reducing churn.

AM / PM toggle:

Step item copy format:

Step [n] · [Product type] [Product name] [1–2 sentence instruction]

Example AM step:

Step 1 · Cleanser CeraVe Hydrating Cleanser Massage onto damp skin for 30 seconds, then rinse with lukewarm water. Do this every morning.

Example PM step:

Step 3 · Treatment The Ordinary Retinol 0.5% Apply a few drops to clean, dry skin. Use every other evening — your skin needs time to adjust.

Completion states:

Share button tooltip: Share my routine

Conflict notice entry point (if applicable):

Edit products button:

Screen 14 — Ingredient conflict detail

Example (Retinol + AHA):

Example (Vitamin C + Niacinamide):

Rationale: Tone is "here's what we did for you" not "here's a warning." User comes to this screen to understand, not to take action — so copy leads with the solution, not the problem.

Screen 15 — Progress screen

Streak copy by milestone:

Empty state (day 1, no data):

Screen 16 — Profile / Settings

Photo picker sheet:

Retake quiz confirmation sheet:

Error & empty states (global)

Screen 17 — Edit products (bottom sheet)

Rationale: Copy is minimal — user has already been through this flow in the quiz. No need to re-explain. "Update my routine" (not "Regenerate") feels like a natural continuation, not a reset.

Screen 18 — Home

Greeting copy:

UV Index badge copy:

Routine card copy:

Streak broken notice:

Skin tip format:

Milestone banner copy:

Rationale: UV badge copy is kept minimal — just the number and one clear action. No "danger" language, no alarmism. First-step preview uses the actual product name so the user immediately recognizes their own routine. Milestone copy is understated by design — patronizing celebrations feel hollow on repeat use.

End of Section 05. Next: Section 06 — Technical Requirements & Constraints.

Section 06 — Technical Requirements & Constraints

iOS requirements

Authentication

In-app purchases & subscriptions

AI routine generation

Important: The Anthropic API key must never be bundled in the iOS app or called directly from the client. All AI calls must go through Aluvi's own backend to protect the key and allow server-side prompt management.

Open Beauty Facts integration

Product recommendation catalog

Data storage & backend

Analytics

All events below must fire correctly before App Store submission.

Analytics provider: TBD — Mixpanel or PostHog recommended. Must support iOS SDK and funnel analysis.

UV Index integration

Security requirements

App Store requirements

End of Section 06. Next: Section 07 — Open Questions & Decisions Log.

Section 07 — Open Questions & Decisions Log

This section tracks decisions still pending, plus all key decisions already made during PRD development. Use this as a living log — update status as decisions are resolved.

Pending decisions

Decided — recorded for reference

v1.1 roadmap candidates

Features explicitly deferred from MVP but confirmed as next priorities:

v2.0 roadmap candidates

End of Section 07.

Document status

Product Owner: Ardho

Last updated: June 2, 2026

Changelog