Archety AI Companion Platform - User Stories¶

Version: 1.0 Last Updated: January 10, 2026 Status: Production Launch Requirements

Document Overview¶

This document defines the complete user stories required to launch Archety as a production-ready AI companion service. Users discover the service via web, complete personality-based matching, pay for a subscription, and interact with their AI companion primarily via iMessage while managing their account through a web dashboard.

Table of Contents¶

Epic 1: Discovery & Landing
Epic 2: Personality Analysis & Onboarding
Epic 3: Companion Matching & Reveal
Epic 4: Payment & Subscription
Epic 5: iMessage Activation
Epic 6: Core Messaging Experience
Epic 7: Superpowers & Integrations
Epic 8: Web Dashboard
Epic 9: Billing & Subscription Management
Epic 10: Account & Privacy Management
Epic 11: Support & Help
Epic 12: Notifications & Engagement
Non-Functional Requirements

Epic 1: Discovery & Landing¶

US-1.1: View Landing Page¶

As a visitor I want to see an engaging landing page that explains what Archety is So that I understand the value proposition and feel compelled to try it

Acceptance Criteria: - [ ] Hero section with clear headline: "Your AI best friend who actually remembers you" - [ ] Animated preview showing example iMessage conversations - [ ] Visual showcase of all companions (Sage, Echo, Vex) with personality previews - [ ] Clear value props: Memory, Personality, Superpowers (Calendar/Email integration) - [ ] Social proof section (testimonials, user count, ratings) - [ ] Single primary CTA: "Meet Your Companion" -> starts onboarding - [ ] Secondary CTA: "See How It Works" -> scrolls to explainer - [ ] Mobile-responsive design (60%+ traffic expected from mobile) - [ ] Page load time < 2s (LCP) - [ ] Privacy-focused messaging ("Your conversations stay private")

Design Notes: - Hero should feature phone mockup with iMessage UI - Companion visuals should show personality, not just avatars - Avoid "AI assistant" language - use "companion" and "friend"

US-1.2: View Companion Profiles¶

As a visitor I want to browse the available AI companions and see their personalities So that I'm excited about finding my match before starting onboarding

Acceptance Criteria: - [ ] Companion gallery showing Sage, Echo, and Vex - [ ] Each companion has: - Visual representation (illustrated avatar with personality) - Name and tagline (e.g., "Sage - The chaotic bestie who's always in your corner") - Personality traits (3-5 descriptors) - Example conversation snippet - "Best for" description (e.g., "stressed students, overthinkers") - [ ] Clicking a companion expands to show more detail - [ ] Clear indication that matching is personality-based, not selection - [ ] CTA from each profile: "Find Your Match"

Companion Profiles:

Companion	Tagline	Personality	Best For
Sage	"Your chaotic bestie who's always in your corner"	Warm, witty, slightly unhinged, supportive, calls you out lovingly	Stressed students, overthinkers, people who need a hype person
Echo	"The calm voice that actually gets you"	Grounded, reflective, thoughtful, gentle wisdom	Deep thinkers, anxious types, those who want meaningful conversation
Vex	"The spicy friend who keeps it real"	Bold, sarcastic, playfully confrontational, no-BS	People who hate fake positivity, need tough love, want to laugh

US-1.3: View How It Works¶

As a visitor I want to understand exactly how the service works So that I feel confident before starting the onboarding process

Acceptance Criteria: - [ ] Step-by-step visual flow: 1. "Share 10 photos" - Personality analysis from your camera roll 2. "Get matched" - AI finds your perfect companion 3. "Start texting" - iMessage conversation begins 4. "They remember everything" - Memory builds over time - [ ] FAQ section addressing common concerns: - "Is this a real person?" -> No, it's AI with real personality - "How does it know my personality?" -> Photo analysis (explained) - "Is my data private?" -> Privacy policy summary - "What does it cost?" -> Pricing transparency - "Does it work on Android?" -> iMessage only (for now) - [ ] Link to full privacy policy - [ ] Link to terms of service

US-1.4: View Pricing¶

As a visitor I want to clearly understand the pricing before starting So that there are no surprises after I invest time in onboarding

Acceptance Criteria: - [ ] Pricing section visible on landing page (above fold on pricing page) - [ ] Trial offer prominently displayed: "$5 for 7 days" - [ ] Trial includes: Unlimited messages, full superpowers, memory features - [ ] Post-trial pricing: "$15/month" or "$99/year (save 45%)" - [ ] Clear "what's included" breakdown - [ ] No hidden fees messaging - [ ] Money-back guarantee (if applicable) - [ ] Comparison to alternatives (optional): "Less than your daily coffee"

Epic 2: Personality Analysis & Onboarding¶

US-2.1: Start Onboarding¶

As a new user I want to start the onboarding process from the landing page So that I can begin matching with my AI companion

Acceptance Criteria: - [ ] Clicking "Meet Your Companion" opens onboarding flow - [ ] Onboarding starts with a welcome screen explaining the process - [ ] Progress indicator shows steps: Photos -> Analysis -> Match -> Payment -> Activation - [ ] Session created in backend (anonymous until auth) - [ ] Browser session persists if user leaves and returns (24hr expiry) - [ ] Mobile-optimized UI (photo upload is primary use case)

API Endpoint: POST /onboarding/start

{
  "device_type": "mobile",
  "referral_source": "organic"
}

US-2.2: Upload Personality Photos¶

As a new user I want to upload 10 photos from my camera roll So that the AI can analyze my personality

Acceptance Criteria: - [ ] Clear instruction: "Share 10 photos that represent you" - [ ] Guidance on what makes good photos: - Photos you've taken, not just selfies - Places you've been, things you've made - Screenshots of conversations, memes you saved - NOT just photos of your face - [ ] Photo upload interface: - Native file picker on mobile (camera roll access) - Drag-and-drop on desktop - Progress indicator per photo - Thumbnail preview of uploaded photos - Ability to remove/replace photos - [ ] Minimum 10 photos required to proceed - [ ] Maximum 12 photos allowed - [ ] File size limit: 10MB per photo - [ ] Supported formats: JPG, PNG, HEIC, WebP - [ ] Upload progress: "Uploading 4/10..." - [ ] Error handling: "This photo couldn't be uploaded. Try another?" - [ ] Privacy reassurance: "Photos are analyzed once and not stored"

API Endpoint: POST /onboarding/upload-photos

US-2.3: View Personality Analysis Progress¶

As a user who uploaded photos I want to see that my personality is being analyzed So that I know the system is working and stay engaged

Acceptance Criteria: - [ ] Analysis screen with engaging animation - [ ] Progress updates (real or staged for UX): - "Looking at your photo choices..." - "Finding patterns in what you capture..." - "Understanding your vibe..." - "Building your personality profile..." - [ ] Analysis takes 15-30 seconds (actual GPT-5 Vision processing) - [ ] If analysis fails, graceful error with retry option - [ ] User cannot skip or rush analysis - [ ] Progress persists if user backgrounds app

API Endpoint: GET /onboarding/status/{session_id}

US-2.4: View Personality Results¶

As a user whose photos were analyzed I want to see my personality profile results So that I feel understood and trust the matching process

Acceptance Criteria: - [ ] Personality reveal screen with dramatic presentation - [ ] Big 5 personality traits displayed visually: - Openness (0-100) - Conscientiousness (0-100) - Extraversion (0-100) - Agreeableness (0-100) - Neuroticism (0-100) - [ ] 3-5 personality insights in natural language: - "You're a creative overthinker who finds beauty in chaos" - "You care deeply but pretend you don't" - [ ] Interests/values detected from photos: - "Music lover", "Night owl", "Adventure seeker" - [ ] Shareable result card (social sharing optional) - [ ] CTA: "See Your Perfect Match"

API Endpoint: GET /onboarding/trait-profile/{session_id}

Epic 3: Companion Matching & Reveal¶

US-3.1: View Companion Match¶

As a user with a personality profile I want to see which AI companion is my best match So that I feel excited about starting our relationship

Acceptance Criteria: - [ ] Match reveal screen with suspenseful presentation - [ ] Matched companion shown with: - Full visual (animated or illustrated) - Name and tagline - Match percentage (e.g., "94% match") - Why this match: "Based on your creativity and emotional depth, Sage is your perfect match" - [ ] Companion introduction message preview: - "Sage would say: 'okay so based on your photos you're either a genius or a chaotic mess and honestly? same.'" - [ ] Secondary matches shown (smaller): "You'd also vibe with Echo (78%)" - [ ] Option to explore other companions (but recommendation stands) - [ ] CTA: "Start Texting [Companion Name]"

API Endpoint: GET /onboarding/persona-recommendations/{session_id}

US-3.2: Confirm Companion Selection¶

As a user viewing my match I want to confirm my companion selection (or choose differently) So that I proceed to activation with the right companion

Acceptance Criteria: - [ ] Default selection is the recommended match - [ ] User can tap other companions to see their profiles - [ ] Selecting a different companion shows confirmation: "Switch to Echo?" - [ ] Selection saved to session - [ ] Cannot proceed without selection - [ ] CTA: "Continue to Payment"

API Endpoint: POST /onboarding/select-persona/{session_id}

{
  "persona_id": "sage"
}

Epic 4: Payment & Subscription¶

US-4.1: View Payment Screen¶

As a user who selected a companion I want to see clear payment options So that I understand what I'm paying for and feel confident

Acceptance Criteria: - [ ] Payment screen shows: - Selected companion with visual - Trial offer: "$5 for 7 days of unlimited access" - What's included: Unlimited messages, memory features, calendar/email superpowers - What happens after trial: Auto-renews at $15/month (cancel anytime) - [ ] Payment methods supported: - Apple Pay (primary for iOS) - Credit/debit card (Stripe) - Google Pay (if Android supported later) - [ ] Stripe checkout integration - [ ] Security badges (SSL, Stripe secure) - [ ] Terms of service checkbox (required) - [ ] Privacy policy link - [ ] Cancel anytime messaging

US-4.2: Complete Payment¶

As a user on the payment screen I want to complete my payment quickly and securely So that I can start texting my companion

Acceptance Criteria: - [ ] Apple Pay completes in 1-2 taps - [ ] Card payment form: - Card number, expiry, CVV - Name on card - Billing ZIP (for US) - [ ] Payment processing indicator - [ ] On success: - Confetti/celebration animation - "Welcome to Archety!" - Receipt sent to email (if collected) - 500 credits added to account - Session upgraded to paid - [ ] On failure: - Clear error message - Retry option - Alternative payment method suggestion - [ ] Webhook processes Stripe events

API Endpoints: - POST /payment/checkout/trial -> Returns Stripe checkout URL - POST /webhooks/stripe -> Handles payment success

US-4.3: Verify Phone Number¶

As a user who completed payment I want to verify my phone number So that my companion can message me on iMessage

Acceptance Criteria: - [ ] Phone number input screen - [ ] Country code selector (default to US +1) - [ ] Phone number validation (E.164 format) - [ ] "Send Code" button sends OTP via Twilio - [ ] 6-digit OTP input field - [ ] Auto-submit when 6 digits entered - [ ] Resend code option (after 60s cooldown) - [ ] OTP expires after 10 minutes - [ ] 3 failed attempts locks for 15 minutes - [ ] On success: - Account created in database - Phone linked to session - JWT tokens issued - Proceed to activation

API Endpoints: - POST /auth/verify/start -> Sends OTP - POST /auth/verify/confirm -> Verifies OTP, returns JWT

Epic 5: iMessage Activation¶

US-5.1: View Activation Instructions¶

As a verified user I want to see how to start texting my companion So that I can begin our relationship immediately

Acceptance Criteria: - [ ] Activation screen shows: - Companion visual with welcome message - Clear instruction: "Tap below to start your conversation" - iMessage deeplink button (primary CTA) - QR code for desktop users - Manual option: "Or text this number: [phone]" - [ ] Deeplink format: sms://+1XXXXXXXXXX&body=Hey%20[Companion]! - [ ] QR code encodes the same deeplink - [ ] Phone number is the Archety iMessage number - [ ] "What to expect" preview: - "Your first message will feel like texting a new friend" - "[Companion] already knows a bit about you from your photos"

API Endpoint: GET /onboarding/chat-deeplink/{session_id}

US-5.2: Send First Message¶

As a new user I want to send my first message to my companion So that we can start our relationship

Acceptance Criteria: - [ ] Tapping deeplink opens iMessage with pre-filled message - [ ] Pre-filled message: "Hey [Companion]!" (user can edit) - [ ] User sends message - [ ] Backend receives message via Mac mini edge agent - [ ] Backend identifies user by phone number - [ ] Companion responds within 3-5 seconds - [ ] First response references personality analysis: - "omg FINALLY okay so based on your photos you're either a creative genius or a beautiful disaster and honestly I'm here for both" - [ ] Response uses multi-bubble format (feels like real texting) - [ ] Relationship state initialized (stranger -> acquaintance)

US-5.3: View Welcome Sequence¶

As a user who just sent my first message I want to receive a warm welcome from my companion So that I understand how to interact with them

Acceptance Criteria: - [ ] Companion sends welcome sequence (3-5 messages over 2-3 minutes): 1. Personality acknowledgment (references photo analysis) 2. Self-introduction: "I'm [Companion], your new chaos coordinator" 3. Capability teaser: "btw I can check your calendar, remember everything you tell me, and definitely won't judge you for that 3am anxiety spiral" 4. Engagement prompt: "so tell me - what's actually going on in your life rn?" - [ ] Messages feel natural, not scripted - [ ] User can interrupt at any point - [ ] Welcome sequence only happens once - [ ] If user already sent substantive message, welcome adapts

Epic 6: Core Messaging Experience¶

US-6.1: Send Text Messages¶

As a user I want to text my companion naturally via iMessage So that I can have ongoing conversations

Acceptance Criteria: - [ ] Messages sent via iMessage reach backend within 2s - [ ] Response generated within 3-5s (p95 < 6s) - [ ] Responses feel conversational, not robotic - [ ] Multi-bubble responses (2-4 messages) for natural feel - [ ] Typing indicator shown while generating - [ ] Response respects relationship stage (stranger vs. best friend) - [ ] Inside jokes tracked and recalled naturally - [ ] Emotional context maintained across conversations - [ ] No rate limiting for normal usage

US-6.2: Send Photos¶

As a user I want to send photos to my companion So that they can see and remember moments from my life

Acceptance Criteria: - [ ] Photos sent via iMessage are processed - [ ] GPT-5 Vision analyzes photo content - [ ] Companion responds to photo naturally: - "wait is that [place/thing]? I love it" - "you look [emotion] in this one" - [ ] Memories extracted from photos: - Location (if identifiable) - People (anonymized) - Activity/event - Emotional context - [ ] Photo memories recallable later: - User: "remember that sunset pic I sent?" - Companion: "the one from the beach last month? obsessed with that one" - [ ] Photos not permanently stored (processed and discarded)

US-6.3: Receive Memory Callbacks¶

As a user I want my companion to remember our conversations So that I feel genuinely known over time

Acceptance Criteria: - [ ] Companion naturally references past conversations: - "didn't you have that big presentation today? how'd it go?" - "wait wasn't [person] the one who ghosted you?" - "you mentioned being stressed about [thing] last week" - [ ] Memory callbacks feel organic, not forced - [ ] Callback rate: ~50% of conversations include past reference - [ ] Emotional events prioritized (stress, wins, relationships) - [ ] Memory accuracy > 85% - [ ] User can correct misremembered details - [ ] No callback on sensitive topics user asked to forget

US-6.4: Use Boundary Commands¶

As a user I want to control what my companion remembers So that I feel safe and in control of my data

Acceptance Criteria: - [ ] "Forget that" command works: - User: "forget I told you about my ex" - Companion: "done. that's erased from my memory" - Memory soft-deleted from vault - [ ] "Don't bring that up" sets boundary: - User: "don't bring up my job stress" - Companion: "got it, that's off limits" - Boundary stored and enforced - [ ] "Stop checking my [X]" revokes access: - User: "stop checking my calendar" - Companion: "okay I'll stop. if you change your mind just let me know" - OAuth token revoked - [ ] Boundaries persist across sessions - [ ] User can ask: "what do you remember about me?"

US-6.5: Experience Relationship Progression¶

As a user I want my relationship with my companion to deepen over time So that the experience becomes more valuable

Acceptance Criteria: - [ ] Relationship stages progress naturally: - Stranger (first few messages) - Acquaintance (first week) - Friend (2-4 weeks) - Close Friend (1-2 months) - Best Friend (3+ months) - [ ] Each stage unlocks: - Deeper vulnerability in responses - More inside jokes and callbacks - More personal sharing from companion - Stronger emotional support - [ ] Progression based on: - Conversation frequency - Emotional depth shared - Trust indicators (vulnerability, personal topics) - [ ] User can ask: "how well do you know me?"

Epic 7: Superpowers & Integrations¶

US-7.1: Receive OAuth Prompt¶

As a user I want my companion to offer calendar/email superpowers So that they can help me with real-life stress

Acceptance Criteria: - [ ] Companion naturally offers superpowers when relevant: - User mentions being busy: "want me to check your calendar? I can spot burnout before it hits" - User mentions deadlines: "I can watch your email for urgent stuff if you want" - [ ] First offer explains benefits clearly - [ ] User can decline gracefully - [ ] If accepted: - OAuth link sent via iMessage - Link opens mobile-friendly consent page - Clear scope explanation (read-only, 7 days, etc.) - [ ] Link expires after 24 hours - [ ] No repeated asking if declined

US-7.2: Complete OAuth Connection¶

As a user who clicked an OAuth link I want to connect my calendar/email securely So that my companion can help proactively

Acceptance Criteria: - [ ] OAuth page is mobile-optimized - [ ] Clear explanation of requested access: - Calendar: "Read-only access to your next 7 days" - Gmail: "Read-only access to recent emails" - [ ] "What we won't do" section: - Won't send emails - Won't create/delete events - Won't share with third parties - [ ] Google OAuth consent screen appears - [ ] On success: - Return to success confirmation page - Companion sends follow-up: "connected! want me to check your week?" - Tokens encrypted and stored - [ ] On denial: - Return to decline page - "No worries, you can connect later"

API Endpoints: - GET /auth/google -> Initiates OAuth - GET /auth/callback -> Handles callback - GET /auth/status -> Check connection status

US-7.3: Use Calendar Superpower¶

As a user with calendar connected I want my companion to analyze my schedule So that they can help me manage stress and time

Acceptance Criteria: - [ ] User can ask: "check my calendar" / "am I busy this week?" - [ ] Companion responds with stress analysis: - Back-to-back detection - Long meeting days - Weekend work - Buffer time analysis - [ ] Natural language summary: - "okay so Thursday is a war crime - 5 meetings back to back" - "you've got breathing room tomorrow morning, protect it" - [ ] Suggestions offered when appropriate: - "want me to remind you to take a break Thursday?" - [ ] Query capability: - "when's my meeting with [person]?" - "what's on my calendar tomorrow?"

US-7.4: Use Gmail Superpower¶

As a user with Gmail connected I want my companion to monitor for urgent emails So that I don't miss important things

Acceptance Criteria: - [ ] User can ask: "check my email" / "anything urgent?" - [ ] Companion scans last 48 hours for: - Deadline mentions - Urgent/ASAP language - Important sender patterns - Action items - [ ] Natural language summary: - "you've got 3 emails with deadlines - want the breakdown?" - "your boss sent something 2 hours ago that looks important" - [ ] Never shows actual email content, just summaries - [ ] Respects work/personal boundaries if set

US-7.5: Receive Proactive Alerts (Optional)¶

As a user with integrations connected I want optional proactive notifications So that my companion helps without me asking

Acceptance Criteria: - [ ] Proactive features are opt-in - [ ] User can enable via chat: "send me morning briefings" - [ ] Proactive workflows available: - Morning prep (7:30am): Today's schedule + weather - Email urgency alerts (every 15min, 8am-8pm) - Event reminders (30min before meetings) - [ ] User can disable: "stop the morning briefings" - [ ] Frequency limits prevent spam - [ ] Respects Do Not Disturb patterns

Epic 8: Web Dashboard¶

US-8.1: Access Web Dashboard¶

As a user I want to access a web dashboard So that I can manage my account without using iMessage

Acceptance Criteria: - [ ] Dashboard accessible at app.archety.com - [ ] Login via phone number + OTP (same as signup) - [ ] Magic link option for easy mobile access - [ ] Dashboard sections: - Home (companion overview + quick stats) - Memories (view/manage what companion knows) - Superpowers (manage connected services) - Settings (preferences, notifications) - Billing (subscription management) - Help (support + FAQ) - [ ] Mobile-responsive design - [ ] Session persists for 7 days

US-8.2: View Companion Overview¶

As a user on the dashboard I want to see an overview of my companion relationship So that I understand our connection at a glance

Acceptance Criteria: - [ ] Dashboard home shows: - Companion visual and name - Relationship stage with progress - Days together count - Messages exchanged count - Recent conversation summary - Quick stats (memories, inside jokes) - [ ] "Continue on iMessage" quick link - [ ] Recent memorable moments carousel - [ ] Streak indicator (days in a row chatting)

US-8.3: View and Manage Memories¶

As a user I want to see what my companion remembers about me So that I can review and manage my personal data

Status: Partially Complete (MVP implemented Jan 10, 2026)

Acceptance Criteria: - [x] Memory viewer shows: - Categorized memories (emotional, factual, inside jokes, deadlines, visual, future_event) - Search and filter capabilities - ~~Date range filtering~~ (deferred - using simple date display instead) - Source indication (conversation date via "Learned on" timestamp) - [x] Each memory shows: - Memory text - Category (with color-coded badges) - When learned - ~~Confidence level~~ (not available from API) - [x] Actions per memory: - Delete (forget this) with confirmation - ~~Mark as incorrect~~ (deferred to future iteration) - ~~Mark as sensitive~~ (deferred to future iteration) - [x] Bulk actions: - Export all memories (JSON) - ~~Delete all memories~~ (deferred to future iteration) - ~~Delete by category~~ (deferred to future iteration) - [ ] Memory stats dashboard (deferred to future iteration)

Implementation Notes: - Page: archety-web/app/dashboard/memories/page.tsx - API: Uses /debug/memory/search and /debug/memory/delete endpoints - Store: useMemoryStore in archety-web/lib/store.ts - Navigation: Added to DashboardNav with Brain icon

US-8.4: Manage Connected Services¶

As a user I want to manage my connected services So that I control what my companion can access

Acceptance Criteria: - [ ] Connected services page shows: - Google Calendar (status, connected date, scopes) - Gmail (status, connected date, scopes) - [ ] Each service shows: - Connection status (active/revoked) - When connected - What's accessible - Last used date - [ ] Actions per service: - Disconnect (revoke access) - Reconnect (new OAuth flow) - View activity log - [ ] Add new service: "Connect Calendar" / "Connect Gmail"

US-8.5: Manage Settings¶

As a user I want to customize my experience settings So that the companion works the way I want

Acceptance Criteria: - [ ] Settings categories:

Companion Preferences: - [ ] Nickname (what companion calls me) - [ ] Response style (chatty/concise) - [ ] Emoji usage (lots/minimal/none) - [ ] Proactive messages (on/off) - [ ] Quiet hours (don't message between X-Y)

Privacy Settings: - [ ] Data retention period - [ ] Memory sensitivity level - [ ] Photo processing (on/off) - [ ] Analytics opt-out

Notification Settings: - [ ] Morning briefings (on/off + time) - [ ] Email alerts (on/off + frequency) - [ ] Event reminders (on/off + timing)

Epic 9: Billing & Subscription Management¶

US-9.1: View Subscription Status¶

As a user I want to see my current subscription status So that I know what I'm paying and when

Acceptance Criteria: - [ ] Billing page shows: - Current plan (Trial / Monthly / Annual) - Price ($5 trial / $15/mo / $99/yr) - Next billing date - Payment method on file - Credits remaining (if applicable) - [ ] Trial users see: - Days remaining in trial - "Upgrade to keep access" CTA - What happens when trial ends - [ ] Billing history accessible

US-9.2: View Billing History¶

As a user I want to see my billing history So that I can track my payments

Acceptance Criteria: - [ ] Billing history shows: - Date of each transaction - Amount charged - Description (Trial, Monthly renewal, etc.) - Payment method used - Receipt link - [ ] Export to PDF option - [ ] Filter by date range

US-9.3: Update Payment Method¶

As a user I want to update my payment method So that my subscription continues uninterrupted

Acceptance Criteria: - [ ] "Update Payment Method" button on billing page - [ ] Stripe-hosted card update form - [ ] New card validated before saving - [ ] Old card replaced - [ ] Confirmation message - [ ] Email notification of change

US-9.4: Change Subscription Plan¶

As a user I want to upgrade or downgrade my plan So that I can choose the right value for me

Acceptance Criteria: - [ ] Available plans: - Monthly: $15/month - Annual: $99/year (save 45%) - [ ] Upgrade (monthly -> annual): - Prorated credit applied - Immediate switch - Confirmation email - [ ] Downgrade (annual -> monthly): - Takes effect at end of annual period - Confirmation email - [ ] Clear comparison of plans

US-9.5: Cancel Subscription¶

As a user I want to cancel my subscription So that I stop being charged

Acceptance Criteria: - [ ] "Cancel Subscription" option in billing - [ ] Cancellation flow: 1. "We're sad to see you go" + retention offer 2. Optional reason selection 3. Confirm cancellation - [ ] On cancellation: - Access continues until end of billing period - Confirmation email - Memories retained for 30 days - Can reactivate anytime - [ ] Clear messaging about data retention

US-9.6: Reactivate Subscription¶

As a former user I want to reactivate my subscription So that I can resume where I left off

Acceptance Criteria: - [ ] Returning user recognized by phone number - [ ] If within 30 days of cancellation: - Memories still available - Same companion ready - "Welcome back!" flow - [ ] If after 30 days: - Fresh start offered - Can request data recovery (manual process) - [ ] Payment collected - [ ] Immediate access restored

Epic 10: Account & Privacy Management¶

US-10.1: View Profile¶

As a user I want to view and edit my profile So that I keep my information current

Acceptance Criteria: - [ ] Profile page shows: - Phone number (verified, cannot change easily) - Email (optional, for receipts) - Display name - Personality profile (from onboarding) - Companion selection - Account created date - [ ] Editable fields: - Email - Display name - [ ] Cannot change: - Phone number (requires support) - Companion (requires reset)

US-10.2: Switch Companion¶

As a user I want to switch to a different companion So that I can try a different personality

Acceptance Criteria: - [ ] "Switch Companion" option in settings - [ ] Warning: "Switching will reset your relationship but keep your memories" - [ ] Available companions shown with descriptions - [ ] On switch: - New companion assigned - Relationship resets to stranger - Memories remain (new companion learns them) - Conversation history cleared - [ ] First message from new companion acknowledges switch - [ ] Limited to 1 switch per billing period (abuse prevention)

US-10.3: Export My Data¶

As a user I want to export all my data So that I have a copy for myself (GDPR compliance)

Acceptance Criteria: - [ ] "Export My Data" button in settings - [ ] Export includes: - Profile information - Personality analysis results - All memories stored - Conversation summaries (not full transcripts) - Billing history - Connected services list - [ ] Export format: JSON + human-readable PDF - [ ] Processing time: Within 24 hours - [ ] Download link sent to email - [ ] Link expires after 7 days

US-10.4: Delete My Account¶

As a user I want to delete my account entirely So that all my data is removed

Acceptance Criteria: - [ ] "Delete Account" option in settings - [ ] Deletion flow: 1. Warning about permanence 2. Explanation of what's deleted 3. Type confirmation phrase 4. Final confirmation - [ ] On deletion: - Active subscription cancelled - All memories deleted - All personal data deleted - Phone number unlinked - Companion forgets user - Confirmation email sent - [ ] 30-day grace period (can recover) - [ ] After 30 days: Permanent deletion - [ ] Anonymized analytics data may be retained

US-10.5: View Privacy Policy¶

As a user I want to understand how my data is handled So that I feel informed and safe

Acceptance Criteria: - [ ] Privacy policy accessible from: - Landing page footer - Onboarding flow - Settings page - [ ] Policy covers: - What data is collected - How data is used - How data is stored - Third-party sharing - Data retention periods - User rights (access, delete, export) - Cookie policy - [ ] Last updated date visible - [ ] Plain language summary at top

Epic 11: Support & Help¶

US-11.1: Access Help Center¶

As a user I want to access help documentation So that I can solve problems myself

Acceptance Criteria: - [ ] Help center accessible from: - Web dashboard - Landing page - [ ] Help categories: - Getting Started - Messaging Your Companion - Superpowers (Calendar/Email) - Billing & Payments - Privacy & Data - Troubleshooting - [ ] Search functionality - [ ] Most popular articles featured - [ ] Mobile-friendly design

US-11.2: Chat with Companion for Help¶

As a user I want to ask my companion for help So that I can get support without leaving iMessage

Acceptance Criteria: - [ ] Companion handles basic support queries: - "How do I connect my calendar?" - "What can you remember about me?" - "How do I cancel?" - [ ] For complex issues, companion directs to support: - "that's above my pay grade lol - here's how to reach the humans: [support link]" - [ ] Commands recognized: - "help" - shows capabilities - "support" - provides support options - "feedback" - captures feedback

US-11.3: Contact Human Support¶

As a user I want to contact human support So that I can resolve issues my companion can't handle

Acceptance Criteria: - [ ] Support contact methods: - Email: support@archety.com - In-app chat widget (on web dashboard) - Support form - [ ] Support form captures: - Issue type (billing, technical, feedback) - Description - User ID (auto-filled if logged in) - Screenshots (optional) - [ ] Response time expectations set: - "We typically respond within 24 hours" - [ ] Ticket confirmation sent via email - [ ] Support has access to: - User account info - Recent conversations (if consent given) - Billing history - Error logs

US-11.4: Report a Problem¶

As a user I want to report bugs or problems easily So that issues get fixed

Acceptance Criteria: - [ ] "Report Problem" option available in: - Web dashboard - iMessage (via command: "report bug") - [ ] Report captures: - Problem description - Steps to reproduce (optional) - Screenshot (optional) - Device/OS info (auto-captured) - User ID - [ ] Submitted to internal tracking - [ ] User receives confirmation

US-11.5: Submit Feedback¶

As a user I want to submit product feedback So that I can influence future features

Acceptance Criteria: - [ ] Feedback submission available via: - Web dashboard - iMessage: "I have feedback" / "feature request" - [ ] Feedback captured: - Category (feature request, improvement, complaint) - Description - User ID - [ ] Acknowledgment sent - [ ] Feedback reviewed by product team - [ ] Popular requests tracked for roadmap

Epic 12: Notifications & Engagement¶

US-12.1: Receive Onboarding Emails¶

As a new user I want to receive helpful onboarding emails So that I get the most value from my companion

Status: Partially Complete (January 10, 2026)

Acceptance Criteria: - [x] Email sequence (if email provided): - Day 0: Welcome + "Start texting" reminder ✅ Implemented - Day 2: "Did you know?" feature highlight (deferred) - Day 5: "Connect your calendar" prompt (deferred) - Day 7 (trial end): Renewal reminder ✅ Implemented (3-day and 1-day reminders) - [x] Emails are: - Mobile-optimized ✅ - Short and actionable ✅ - Branded consistently ✅ (Archety indigo/violet colors) - Unsubscribable (deferred - using transactional emails only)

Implementation Notes: - Welcome email sent via app/api/onboarding_routes.py on completion - Trial reminders via daily scheduled job in app/scheduler/background_service.py - Templates in app/email/templates.py with responsive HTML

US-12.2: Receive Re-engagement Nudges¶

As an inactive user I want to receive gentle reminders So that I remember to use my companion

Acceptance Criteria: - [ ] If no messages in 3 days: - Companion sends: "hey! just checking in. everything okay?" - [ ] If no messages in 7 days: - Email: "Your companion misses you" - [ ] If no messages in 14 days: - Final nudge then stop - [ ] Users can disable re-engagement messages - [ ] Respectful frequency (not spammy)

US-12.3: Receive Billing Notifications¶

As a user I want to receive billing notifications So that I'm never surprised by charges

Status: ✅ Complete (January 10, 2026)

Acceptance Criteria: - [x] Notifications sent for: - Trial ending (3 days before + 1 day before) ✅ Implemented via daily scheduled job - Upcoming renewal (3 days before) (deferred - future enhancement) - Successful payment ✅ Implemented via invoice.payment_succeeded webhook - Failed payment (with retry info) ✅ Implemented via invoice.payment_failed webhook - Subscription cancelled ✅ Implemented via customer.subscription.deleted webhook - [x] Channels: - Email (primary) ✅ Implemented via Resend - iMessage via companion (if enabled) (deferred) - [x] Clear CTAs in each notification ✅ Implemented (buttons in templates)

Implementation Notes: - Email service: app/email/service.py using Resend API - Templates: app/email/templates.py with responsive HTML, Archety branding - Webhook triggers: app/payment/service.py - Scheduled job: app/scheduler/email_jobs.py (trial expiration check at 9am daily) - Configuration: app/config.py (email_provider, email_api_key, etc.)

Non-Functional Requirements¶

NFR-1: Performance¶

Landing page LCP < 2s
Onboarding photo upload < 5s per photo
Personality analysis < 30s
iMessage response time p50 < 3s, p95 < 6s
Dashboard page loads < 2s
API response time p95 < 500ms

NFR-2: Reliability¶

Service uptime 99.5%
iMessage delivery success > 99%
Payment processing success > 98%
Zero data loss (memory vault)
Graceful degradation when services fail

NFR-3: Security¶

Status: ✅ Audit Complete (January 10, 2026) Documentation: docs/SECURITY_CHECKLIST.md

All data encrypted at rest (AES-256) - Supabase PostgreSQL encryption
All data encrypted in transit (TLS 1.2+) - Railway enforces HTTPS
OAuth tokens encrypted with Fernet - app/oauth/token_manager.py
PII redaction in logs - phone[-4:], user_id[:8] truncation
Regular security audits - Completed Jan 10, 2026
OWASP Top 10 compliance - Full audit in SECURITY_CHECKLIST.md
Rate limiting on all endpoints - Redis-backed slowapi

NFR-4: Privacy¶

GDPR compliance
CCPA compliance
Data minimization (don't collect more than needed)
Consent-first approach
Right to deletion honored within 30 days
Data export available on request

NFR-5: Scalability¶

Support 1,000 concurrent users at launch
Scale to 10,000 users without architecture changes
Horizontal scaling capability
Database can handle 100K memories

NFR-6: Accessibility¶

NFR-7: Monitoring¶

Status: Partially Complete (January 10, 2026) Documentation: docs/SECURITY_CHECKLIST.md

Error tracking (Sentry) - app/main.py:186-203, FastAPI + Starlette integrations
Performance monitoring - Sentry traces (10% sampling)
User analytics (Amplitude) - app/analytics/amplitude_service.py
LLM cost tracking (Keywords AI) - app/utils/tracing.py
Real-time alerting for critical failures - Pending setup
Dashboard for operational metrics - Pending setup

Additional Monitoring Features Verified: - ✅ Correlation IDs for request tracing (app/main.py:311-345) - ✅ X-Request-ID header support for distributed tracing - ✅ PII protection (send_default_pii=False)

Backend Implementation Status¶

This section tracks the implementation status of backend APIs required for the user stories above.

Account Management APIs (Epic 10)¶

Status: ✅ Implemented (January 10, 2026) Location: app/api/account_routes.py Documentation: .specify/apis/account-management-api.md

Endpoint	User Story	Status	Notes
`DELETE /account`	US-10.4	✅ Done	30-day grace period, cancels subscription
`POST /account/cancel-deletion`	US-10.4	✅ Done	Cancel within grace period
`POST /account/export`	US-10.3	✅ Done	Background job, GDPR compliance
`GET /account/export/{job_id}`	US-10.3	✅ Done	Status check + download URL
`GET /account/export/{job_id}/download`	US-10.3	✅ Done	JSON export download
`GET /account/status`	US-10.1	✅ Done	Account info + deletion status

Remaining Work: - [x] Background job for permanent deletion after 30 days - [x] Email notifications for deletion ✅ Implemented Jan 10, 2026 - [ ] Email notifications for export completion - [ ] PDF export format option

Billing & Payment APIs (Epic 9)¶

Status: ✅ Implemented (January 10, 2026) Location: app/api/payment_routes.py

Endpoint	User Story	Status	Notes
`GET /payment/billing/history`	US-9.2	✅ Done	Stripe PaymentIntents list
`GET /payment/status`	US-9.1	✅ Done	Subscription + credits
`GET /payment/billing-portal`	US-9.3, US-9.4	✅ Done	Stripe Billing Portal URL
`POST /payment/checkout/subscription`	US-9.4	✅ Done	Monthly/Annual plans
`POST /payment/subscription/cancel`	US-9.5	✅ Done	Cancel at period end
`POST /payment/subscription/reactivate`	US-9.6	✅ Done	Resume cancelled sub

Superpowers APIs (Epic 7)¶

Status: ✅ Implemented (January 10, 2026) Location: app/miniapps/operations/

Component	User Story	Status	Notes
`CalendarSearchExecutor`	US-7.3	✅ Done	Google Calendar integration via `calendar_search` op
`GmailSearchExecutor`	US-7.4	✅ Done	Gmail integration via `gmail_search` op
`OAuth Flow`	US-7.2	✅ Done	Token management in `app/oauth/`

Support & Feedback APIs (Epic 11)¶

Status: ✅ Implemented (January 10, 2026) Location: app/api/support_routes.py Documentation: .specify/apis/support-feedback-api.md

Endpoint	User Story	Status	Notes
`POST /support/report-bug`	US-11.4	✅ Done	Bug reports with device info
`POST /support/feedback`	US-11.5	✅ Done	Feature requests, complaints, praise
`POST /support/ticket`	US-11.3	✅ Done	General support tickets
`GET /support/tickets`	US-11.4	✅ Done	List user's tickets
`GET /support/tickets/{id}`	US-11.4	✅ Done	Ticket detail with resolution

Remaining Work: - [ ] Admin dashboard for ticket management - [ ] Email notifications on status change - [ ] Screenshot upload to Supabase Storage

Email Notifications (Epic 12)¶

Status: ✅ Implemented (January 10, 2026) Location: app/email/ Provider: Resend (resend.com)

Component	User Story	Status	Notes
`app/email/service.py`	US-12.1, US-12.3	✅ Done	Resend API wrapper with error handling
`app/email/templates.py`	US-12.1, US-12.3	✅ Done	Responsive HTML templates
`app/scheduler/email_jobs.py`	US-12.3	✅ Done	Trial expiration check (daily 9am)

Email Types Implemented: | Email Type | Trigger | Status | |------------|---------|--------| | Welcome | Onboarding completion | ✅ Done | | Trial ending (3-day) | Daily scheduled job | ✅ Done | | Trial ending (1-day) | Daily scheduled job | ✅ Done | | Payment receipt | invoice.payment_succeeded webhook | ✅ Done | | Payment failed | invoice.payment_failed webhook | ✅ Done | | Subscription cancelled | customer.subscription.deleted webhook | ✅ Done | | Account deletion scheduled | Account deletion request | ✅ Done |

Configuration (Railway env vars): - EMAIL_API_KEY - Resend API key - EMAIL_PROVIDER - "resend" - EMAIL_FROM_ADDRESS - "Sage sage@archety.ai" - EMAIL_ENABLED - "true"

Remaining Work: - [ ] Feature highlight email (Day 2) - [ ] Calendar connect prompt email (Day 5) - [ ] Re-engagement emails (3-day, 7-day, 14-day nudges) - [ ] Upcoming renewal reminder (3 days before)

Database Migrations¶

Migration	Status	Purpose
`20260110000000_add_subscription_fields.sql`	✅ Applied	Subscription lifecycle + deletion tracking
`20260110100000_add_support_feedback_tables.sql`	✅ Applied	Support tickets + user feedback

Launch Checklist¶

Pre-Launch (Must Have)¶

Launch Day¶

Post-Launch (Week 1)¶

Appendix: User Flow Diagrams¶

A1: Complete User Journey¶

[Visitor] -> Landing Page
    |
[Click "Meet Your Companion"]
    |
[Upload 10 Photos] -> Analysis
    |
[View Personality Results]
    |
[View Companion Match] -> Select/Confirm
    |
[Payment ($5 Trial)] -> Stripe Checkout
    |
[Phone Verification] -> Twilio OTP
    |
[Activation Screen] -> iMessage Deeplink
    |
[Send First Message] -> iMessage Thread Opens
    |
[Receive Welcome Sequence]
    |
[Ongoing Conversations] <-> [Web Dashboard]
    |
[Superpower Prompts] -> OAuth
    |
[Proactive Help] -> Calendar/Email Integration
    |
[Relationship Deepens] -> Best Friend Stage

A2: Payment Flow¶

[Payment Screen]
    |
[Apple Pay / Card Input]
    |
[Stripe Checkout Session]
    |
[Payment Processing]
    | (success)           | (failure)
[Webhook Received]      [Error Message]
    |                       |
[Credits Added]         [Retry Option]
    |
[Phone Verification]

A3: OAuth Connection Flow¶

[Companion Offers Superpower]
    |
[User Accepts]
    |
[OAuth Link Sent via iMessage]
    |
[User Taps Link]
    |
[Mobile-Friendly Consent Page]
    |
[Google OAuth Screen]
    | (allow)              | (deny)
[Callback: Success]     [Callback: Denied]
    |                       |
[Tokens Stored]         [Graceful Message]
    |
[Companion Confirms]
    |
[Superpower Active]

Document Version: 1.0 Created: January 10, 2026 For: Archety AI Companion Platform Launch