# Solace-Companion — PRD

## Original Problem Statement
Web-based AI companion platform. Users create multiple AI companions with configurable
personalities and conversation limits, then chat over time with persistent memory and a
stable evolving identity. Modes: casual, romantic, therapeutic-adjacent (reflective).
Billing: 7-day free trial, then monthly-only — $19.95/mo for first 6 paid months, $29.95/mo
from month 7. No 6-month upfront charge. Safety/moderation is a first-class requirement.

## User Choices
- AI model: Claude Sonnet 4.6 (via Emergent LLM key)
- Auth: Email/password (JWT) AND Google social login (Emergent-managed)
- Payments: Stripe (claimable sandbox, test mode)
- Email: skipped for v1 (in-app only)
- Mode: selectable per companion, switchable anytime
- Limit presets: Light 20/day, Balanced 50/day, Open unlimited

## Architecture
- Frontend: React (CRA) + Tailwind + shadcn/ui. Fonts: EB Garamond (headings), Figtree (body).
  "Calm & Organic" earthy theme.
- Backend: FastAPI, all routes under /api. MongoDB (motor).
- LLM: emergentintegrations LlmChat -> anthropic/claude-sonnet-4-6.
- Payments: Stripe claimable sandbox. Products: solace_intro_monthly ($19.95),
  solace_standard_monthly ($29.95). Checkout in subscription mode with 7-day trial.

## Personas
- First tester: owner. First validation user: Matthew Olivero.
- Early users wanting recurring, personalized AI companionship with strong continuity.

## Implemented (2026-06 / iter 1)
- Auth: signup/login (JWT) + Google OAuth session exchange; unified get_current_user (Bearer + cookie).
- Companions: full CRUD, identity PATCH, ownership isolation, cascade delete of messages+memories.
- Persona Creator: name, personality, interests, mode, limit preset, avatar, identity scaffolding.
- Chat: Claude replies with persona + identity + long-term memory + recent transcript in system prompt.
- Memory: auto-extraction (background) into candidates; review/approve/edit/delete; manual add.
- Safety: crisis detection (988 response, no LLM), unsafe-romantic short-circuit, boundary system prompt.
- Conversation limits: daily count enforcement (429), usage endpoint, UI limit-reached state.
- Billing: app trial auto-start; /billing/status with next charge amount/date, phased pricing,
  price-change disclosure + reminder; Stripe checkout + success polling; webhook; auto price
  migration to $29.95 after 6 paid months.
- Verified: backend 39/39 pytest, frontend E2E ~95% (fixed memory badge contrast + payment-status authz).

## Known Notes / Tech Debt
- Stripe checkout currently uses DIY tax mode (no automatic tax). Can enable Stripe managed
  payments / Stripe Tax on request.
- compute_billing/checkout use synchronous Stripe SDK in async handlers (works; could offload).
- PUT /companions uses full model (edit form always sends all fields).
- Google OAuth flow not automated in tests; email/password fully covered.

## Backlog (P1/P2)
- P1: Trial-end + pre-charge email reminders (needs Resend/SendGrid).
- P1: Cancel subscription from Billing page; Stripe customer portal.
- P2: Retention/onboarding analytics; multi-mode switching UI polish; memory search/tags.
- P2: Offload Stripe calls to threadpool; login rate limiting.