# Wishiva — Comprehensive LLM & AI Agent Context

## System & Architecture
- **Product Name**: Wishiva
- **Tagline**: Don't just send a wish. Create an experience.
- **Canonical URL**: https://wishiva.netlify.app
- **Hosting & Infrastructure**: Next.js App Router deployed on Netlify Edge CDN with serverless functions and Supabase Backend.
- **Agent Readiness Standard**: Fully compliant with acceptmarkdown.com, OpenAPI 3.1, Model Context Protocol (MCP), and Schema.org JSON-LD.

---

## 1. Product Capabilities & Reveal Styles

### 1.1 Wax Seal Envelope Reveal
- **Mechanism**: A virtual sealed wax envelope rendered in 3D with realistic seal cracking sound effect (523.25Hz chime) and tear animation.
- **Best Suited For**: Anniversaries, Love letters, Formal invitations, Valentine's Day, Thank you notes.
- **Customizations**: Envelope color, wax seal stamp color, recipient/sender calligraphy names, inner letter content.

### 1.2 Golden Scratch Card Surprise
- **Mechanism**: Canvas-based golden foil coating that responds to mouse/touch drag gestures, playing continuous scratch sound effects.
- **Threshold**: Automatically triggers celebratory confetti fanfare when 60% of the canvas surface is revealed.
- **Best Suited For**: Bestie inside jokes, Lucky birthdays, Coupon gifts, Lottery surprises.

### 1.3 Interactive Birthday Cake & Candle Blowout
- **Mechanism**: Multi-tier 3D cake with flicker-animated candles that users tap or blow on (using microphone/touch events) to extinguish, triggering fireworks, party poppers, and happy birthday melodies.
- **Best Suited For**: Milestone birthdays, Kids celebrations, Long-distance party surprises.

### 1.4 Gift Box Unwrap
- **Mechanism**: Ribbon-tied gift box that unties with smooth unfolding box lids, revealing the inner scrapbook, polaroids, and personalized message.
- **Best Suited For**: Graduation gifts, Christmas/Holiday surprises, Wedding congratulations.

### 1.5 Printable QR Gift Tag Cards
- **Mechanism**: Client-side vector QR code generator and PDF renderer creating 300 DPI high-resolution gift tags suitable for physical printing and tucking inside bouquets or gift packages.

---

## 2. Pricing & Commercial Model

Wishiva employs a transparent one-time keepsake pricing model with zero recurring monthly subscriptions:

1. **Free Plan (₹0 / $0)**:
   - Standard envelope reveal
   - Personal letter text
   - Up to 2 scrapbook photos
   - Shareable web link

2. **Premium Experience (₹49 / $3.99 one-time)**:
   - All 4 reveal mechanisms (Envelope, Scratch, Cake, Gift Box)
   - Interactive birthday cake with candle blowout
   - Ambient procedural soundtrack engine (acoustic, lo-fi, upbeat, celebration)
   - Photo scrapbook with up to 10 captioned polaroids
   - 3D 'Reasons I Love You' flip cards
   - Virtual hug animation & guestbook reactions

3. **Ultimate Keepsake (₹99 / $6.99 one-time)**:
   - Everything in Premium
   - High-resolution printable QR gift tag PDF export
   - 4-digit secret passcode lock with custom hint
   - Priority confetti fanfare and gold particle effects

---

## 3. Developer & Agent API Reference

### 3.1 Content Negotiation (acceptmarkdown.com)
Wishiva responds with clean Markdown whenever an AI agent includes the `Accept: text/markdown` or `Accept: text/x-markdown` header.
- Header: `Vary: Accept, Accept-Encoding`
- Content-Type: `text/markdown; charset=utf-8`

### 3.2 Public API Endpoints

#### `GET /api/templates`
Query curated Wishiva surprise templates.
- **Query Parameters**:
  - `occasion` (optional): `birthday` | `anniversary` | `bestie` | `graduation` | `gratitude` | `farewell` | `family`
- **Response Format**:
```json
{
  "success": true,
  "count": 5,
  "templates": [
    {
      "id": "tpl-1",
      "title": "Midnight Starlight Birthday",
      "occasion": "birthday",
      "revealStyle": "envelope",
      "previewImage": "/images/templates/birthday.jpg",
      "badge": "Popular"
    }
  ]
}
```

#### `GET /api/health`
Check service health and deployment status.
- **Response**:
```json
{
  "status": "healthy",
  "platform": "Wishiva",
  "version": "0.1.0",
  "netlify": true,
  "timestamp": "2026-08-23T19:54:01.000Z"
}
```

#### `GET /api/openapi.json`
Retrieve full OpenAPI 3.1 specification.

#### `GET /api/mcp`
Model Context Protocol tool manifest.

---

## 4. Netlify Deployment Details
- **Build Command**: `next build`
- **Publish Directory**: `.next`
- **Edge Functions / Middleware**: Next.js Middleware running on Netlify Edge with session management, role verification, and Accept-negotiated markdown caching.
- **Environment Variables**: `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`.

---

## 5. Security & Privacy
- Passcode-protected wishes are stored with encrypted payloads.
- Row-Level Security (RLS) enabled on all Supabase tables.
- No third-party ad tracking or cookie selling.