Closer/docs/date-planning-roadmap.md

# Date Planning Feature Roadmap

## Vision

Build a complete Date Operating System for Closer — not a simple list of date ideas.

Most couples don't struggle to find ideas. They struggle to:
- Decide what to do
- Find something both partners want
- Schedule it
- Follow through
- Remember meaningful moments afterward

The goal is to create a system that helps couples plan, experience, and reflect on dates together — built on top of Closer's existing daily question + spin wheel engagement loop.

## Goals

### Primary Goals
- Increase relationship engagement beyond daily questions
- Encourage regular quality time
- Create meaningful shared memories
- Improve user retention
- Create premium upgrade opportunities

### Success Metrics
- Dates planned per month
- Dates completed per month
- Couple retention
- Premium conversion rate
- Date reflection completion rate

## Existing App Context

### What's Already Built
- Daily question core loop (answer → reveal → history)
- Spin wheel category picker + question sessions
- Question packs with premium gating
- Partner invite system (code + email)
- Firestore-backed auth, couples, sessions, threads
- RevenueCat SDK wired (`purchases:8.20.0`) — purchase flows not yet implemented
- FCM push notifications (daily reminders, partner answered)
- Room local database (answers, questions, categories)
- Hilt DI, Material 3, Jetpack Compose

### Stack
| Layer | Technology |
|-------|-----------|
| Language | Kotlin 2.x |
| UI | Jetpack Compose + Material 3 |
| Navigation | Navigation Compose |
| Backend | Firebase (Auth, Firestore, Functions, FCM, Remote Config) |
| Payments | RevenueCat (`purchases:8.20.0`) |
| Local Storage | Room + DataStore + EncryptedSharedPreferences |
| DI | Hilt |
| Analytics | Firebase Analytics (hashed IDs, coarse categories) |
| Security | ProGuard/R8, SSL pinning, App Check, fail-closed webhooks |

### Architecture Fit
New date planning features slot into the existing architecture:
```
app/
├── data/
│   ├── local/        # Room: date history, reflections, bucket list
│   ├── remote/       # Firestore: shared date plans, couple bucket list
│   └── repository/   # Repository implementations
├── domain/
│   ├── model/        # Date, DatePlan, BucketListItem, Reflection data classes
│   └── repository/   # Repository interfaces
├── ui/
│   ├── dates/        # NEW: date discovery, match, builder, history, reflection
│   ├── questions/    # Existing daily question flow
│   ├── wheel/        # Existing spin wheel
│   └── ...
├── core/
│   ├── navigation/   # New AppRoute.Dates section
│   ├── billing/      # Premium date pack gating
│   └── ...
```

## Phase 1: Date Discovery

### Date Match

Both partners browse date ideas independently — like the existing question reveal mechanic, but for dates.

Actions:
- Love ❤️
- Maybe 💛
- Skip 👎

Only mutual "Love" matches appear. "Maybe" matches surface as secondary suggestions.

**Firestore model:**
- `couples/{coupleId}/date_swipes/{dateId}` — per-partner swipe state
- Revealed matches stored in `couples/{coupleId}/date_matches/{matchId}`

### Date Builder

Both partners contribute preferences. Builder assembles a plan.

Inputs:
- Date
- Time
- Budget
- Duration

Outputs:
- Activity suggestion
- Food suggestion
- Conversation prompts (draw from existing question packs)
- Optional challenge

**Local-first:** Builder preferences stored in Room. Generated plan synced to Firestore couple doc.

### Couple Bucket List

Shared list both partners can add to and check off.

Categories (aligned with existing question categories):
- Adventure
- Travel
- Food
- Learning
- Romance
- Intimacy
- Seasonal

**Firestore model:**
- `couples/{coupleId}/bucket_list/{itemId}` — shared list with added-by, completed-by, completed-at fields

## Phase 2: Date History and Reflection

### Date History

Store completed dates for the couple.

Fields:
- Date, time, location
- Photos (Firebase Storage)
- Notes (per partner)
- Category
- Cost
- Rating (1–5, per partner)

**Firestore model:**
- `couples/{coupleId}/date_history/{dateId}` — shared history
- Photos stored in Firebase Storage under `couples/{coupleId}/date_photos/{photoId}`

### Private Date Reflection

After a date, both partners answer reflection questions privately. Answers reveal when both complete — same mechanic as the existing answer reveal flow.

Questions:
- What was your favorite moment?
- What surprised you?
- What did you appreciate most?

This reuses the existing `sessions`/`answers`/`threads` Firestore structure but with a date reflection type flag.

### Relationship Insights

Aggregate from date history + existing question engagement.

Track:
- Connection score (composite: date frequency + question engagement + reflection completion)
- Date satisfaction (average rating)
- Date frequency (per month)
- Preferred categories (from date history + question packs)

**Computed client-side** from local Room cache + Firestore snapshots. No server aggregation needed for MVP.

## Phase 3: Smart Planning

### AI Date Concierge

Firebase Cloud Function that generates personalized date plans.

Inputs:
- Budget
- Available time
- Weather (OpenWeather API or similar)
- Interests (from question categories + date history)
- Relationship stage (from account age + date history)

Outputs:
- Complete itinerary
- Estimated cost breakdown
- Conversation prompts (pull from existing premium question packs)
- Backup indoor plan

**Implementation:** Firebase Cloud Function calling an LLM API (OpenAI / Anthropic). Results cached in Firestore.

### Smart Scheduling

Track partner availability and suggest date windows.

- Availability shared via Firestore (simple "free evenings" or calendar integration later)
- Preferred date frequency set per couple
- Auto-suggest when both partners have a free window + haven't had a date recently

## Premium Features

### Premium Date Packs

Curated date collections — same pack model as existing question packs.

- First Year Together
- Married With Kids
- Long Distance
- Anniversary Pack
- Reconnection Pack
- Summer Dates
- Winter Dates

**Implementation:** Same Firestore pack structure + RevenueCat entitlement gating as existing question packs.

### Advanced AI Concierge

- Unlimited AI-generated plans (free tier: 1/month)
- Personalized recommendations based on date history
- Seasonal suggestions
- Local event integration (later: Google Places / Yelp API)

### Premium Insights

- Date trends over time
- Relationship growth patterns
- Favorite activities
- Monthly summaries

## Killer Feature: Date Replay

Both partners answer after a date:
- Best moment
- Unexpected moment
- One thing I appreciated

Months later, they can revisit those reflections as a relationship timeline — like the existing answer history, but for real experiences.

**Implementation:** Reuses the reveal mechanic. Reflections stored as date-typed sessions. Timeline view queries all completed date sessions sorted chronologically.

## Recommended Build Order

### MVP — Phase 1 (v1.1.x)

1. **Date Match** — swipe UI + mutual match reveal (reuses reveal pattern)
2. **Date Builder** — preference input + plan generation
3. **Couple Bucket List** — shared list with checkoff

### Version 1.2

4. **Date History** — log completed dates + photos
5. **Private Reflections** — post-date questions with reveal mechanic
6. **Relationship Insights** — aggregate dashboard

### Version 1.3

7. **Smart Scheduling** — availability + suggestions
8. **AI Date Concierge** — Cloud Function + LLM integration

### Version 2.0

9. **Date Replay** — relationship timeline from reflections
10. **Advanced Analytics** — trends + growth patterns
11. **Premium Date Packs** — curated collections
12. **Local Event Integration** — Places/Yelp API

## Long Term Positioning

Closer becomes a full relationship platform where couples can:
- Communicate (daily questions, spin wheel)
- Plan experiences (date match, builder, AI concierge)
- Build memories (date history, reflections, replay)
- Track relationship growth (insights, analytics)
- Strengthen connection over time

Every feature builds on the same engagement loop: **private input → mutual reveal → shared memory**.