# Love Letter Studio โ€” Complete Technical & Architectural Specification (LLMs-Full) ================================================================================ TABLE OF CONTENTS ================================================================================ 1. Executive Summary & Brand Philosophy 2. System Architecture & Tech Stack 3. Ephemeral Security & 15-Day Privacy Model 4. The 7-Act Interactive Keepsake Journey (Act Pipeline) 5. Visual Design System & Aesthetic Worlds (11 Themes) 6. Procedural Audio Intelligence & Sound Design 7. AI & LLM Studio Architecture (Multi-Provider Engine) 8. Complete REST API Reference (Request / Response Schemas) 9. Database Architecture (SQLite & MySQL Production Mappings) 10. SEO, AEO (Answer Engine) & GEO (Generative Engine) Optimization 11. Hostinger cPanel / Apache / LiteSpeed Deployment Guide 12. Maintenance, Purging & Disaster Recovery Directives ================================================================================ 1. EXECUTIVE SUMMARY & BRAND PHILOSOPHY ================================================================================ Love Letter Studio (https://loveletter.friskysoftsell.in) is an elite, artisanal web application dedicated to creating bespoke, interactive digital love capsules and keepsakes. Designed by FRISKYSOFTSELL and Simerdeep Singh, the platform combines the timeless intimacy of 19th-century epistolary romance with cutting-edge 21st-century web animation, Web Audio synthesis, and Large Language Model intelligence. Core Tenets: - Ephemeral Intimacy: Love letters are not meant for perpetual public broadcast. Each keepsake is strictly unlisted, accessible only via a secure 12-character token, and lives for a window of exactly 15 calendar days before graceful expiration. - Zero-Dependency Purity: The entire user interface is constructed with Vanilla HTML5, Vanilla CSS3, and ESNext JavaScript. No React, no Vue, no Tailwind, no npm runtime dependencies. This guarantees near-instant page loads (LCP < 0.8s), zero bundle thrashing, and lifetime stability. - Multi-Sensory Engagement: Keepsakes are not static web pages; they are theatrical experiences engaging sight (60 FPS petal physics, custom themes), sound (procedural acoustic harp chords, audio-reactive crackles), and touch (interactive wax breaking, candle blowing, playful button evasion). ================================================================================ 2. SYSTEM ARCHITECTURE & TECH STACK ================================================================================ Client-Side Stack: - Markup: Semantic HTML5 with explicit accessibility affordances, ARIA roles, and micro-data tags. - Styling: Pure CSS3 utilizing custom property design tokens (:root variables), hardware-accelerated transforms (transform3d, will-change), and responsive clamp() scales. - Scripting: Modular Vanilla JavaScript (ESNext). Encapsulated in immediately invoked function expressions (IIFE) with clean event delegation. - Audio Synthesis: Web Audio API (AudioContext, OscillatorNode, GainNode, BiquadFilterNode) delivering offline procedural harp and lofi chords without downloading external audio files. - Graphics & Physics: HTML5 2D Canvas for particle simulation (petals, stardust, confetti) operating with device-pixel-ratio capping (Math.min(devicePixelRatio, 2)) for thermal efficiency on mobile devices. Server-Side Stack: - Runtime: Python 3.10+ Standard Library. Zero pip dependencies for baseline operations. - Server Framework: http.server.ThreadingHTTPServer with custom subclassed request dispatchers. - Database Engine: SQLite3 in Write-Ahead-Logging (WAL) mode with synchronous=NORMAL and busy_timeout=10000ms. - Alternative Database: MySQL 8.0+ / MariaDB compatible for Hostinger shared hosting environments. - Image Processing: Optional Pillow (PIL) for server-side thumbnail generation, with graceful client-side HTML5 canvas compression fallback. ================================================================================ 3. EPHEMERAL SECURITY & 15-DAY PRIVACY MODEL ================================================================================ Privacy Guarantees: 1. Unlisted Links: Keepsakes receive cryptographic 12-character hexadecimal identifiers (e.g., `8742158c6b65`) generated via Python's `secrets.token_hex(6)`. These URLs are never listed in public directories or site indexes. 2. Search Engine Barricade: All recipient endpoints (`/surprise.html`, `/s/*`, `/surprise/*`) are tagged with `` and disallowed in `robots.txt`. 3. 15-Day Expiration: Upon creation, an exact timestamp is recorded (`expires_at = created_at + 15 days`). After this timestamp, requests to the capsule receive HTTP 410 Gone with a gentle, poetic expiry notification. 4. Two-Phase Automated Data Hygiene: - Phase 1 (Day 15): Public URL goes quiet. Recipient viewing is disabled. - Phase 2 (Day 25 / 10 Days Post-Expiry): An autonomous background worker permanently purges the private letter text and personal reasons from the database (`UPDATE surprises SET letter = '[Purged per retention policy]'`). 5. Anti-Abuse Rate Limiting: Creators are restricted to 1 active keepsake per phone number / email address every 15 calendar days to prevent automated spamming and maintain artisanal exclusivity. ================================================================================ 4. THE 7-ACT INTERACTIVE KEEPSAKE JOURNEY ================================================================================ When a recipient opens their private link, they enter a guided 7-act interactive theater: Act 1: The Sealed Envelope - Visual: An authentic textured parchment envelope sealed with a stamped 3D wax seal bearing the creator's initial. - Interaction: The recipient clicks or taps the wax seal. - Audio/Physics: Web Audio generates a crisp mechanical wax-fracture sound effect. The envelope flap rotates upwards along the X-axis in 3D perspective, revealing the folded stationery inside. Act 2: The Handwritten Fountain Pen Letter - Visual: A textured stationery sheet unfolds smoothly into view. - Typography: Authentic cursive fountain pen script ('Playfair Display' / 'Dancing Script') rendering the sender's personalized letter. - Atmosphere: A gentle procedural acoustic harp chord progression commences, looping seamlessly in the background. Act 3: Three Little Truths - Visual: Three bespoke cards appearing with staggered delays (150ms intervals). - Content: The creator's three specific reasons why they love, admire, or celebrate the recipient. - Micro-interactions: Cards feature subtle 3D hover lifts, glowing gold borders, and ambient stardust particles. Act 4: Memory Photo Vault - Visual: Up to 6 curated memories styled as physical polaroid photographs casually resting on the desk. - Interaction: Clicking any photo enlarges it into a lightbox with gentle floating rotation and ambient caption display. - Optimization: Images are pre-compressed on the creator's device to max 1600px width at 0.82 JPEG quality, ensuring instant mobile loading. Act 5: Cake & Candle Ceremony - Visual: A customized celebration cake matching the occasion (Birthday, Anniversary, Valentine's) with chosen cake flavors (e.g., Strawberry Shortcake with Chantilly Cream) and 1 to 5 interactive flickering candles. - Interaction: The recipient taps the cake or candles to "blow them out". - Physics: Flame particles dissipate into wispy smoke trails, candle wicks darken, and a festive chime sounds. Act 6: Sassy Runaway Question - Concept: A playful affirmation question (e.g., "Will you keep choosing this with me, every single day?") with two buttons: "Yes, absolutely! ๐Ÿ’–" and "Let me think ๐Ÿค”". - Physics: The "Let Me Think" button is equipped with evasion physics. When the cursor or touch approaches within 80 pixels, the button calculates the approach vector and flees to an alternate safe coordinate within its bounding container. - Emotional Tone: Playful, lighthearted, and designed to elicit an affectionate laugh. Act 7: The Grand Finale - Visual: Upon clicking the positive affirmation button, a full-screen canvas confetti cannon discharges multicolored foil ribbons and golden hearts. - Audio: The background soundtrack swells into a triumphant, harmonic acoustic cadence. - Persistence: The recipient is shown a completion receipt and can bookmark the page to replay during the remaining 15-day window. ================================================================================ 5. VISUAL DESIGN SYSTEM & AESTHETIC WORLDS (11 THEMES) ================================================================================ The studio provides 11 distinct aesthetic worlds. Each world defines a coherent emotional universe via CSS variables: 1. Rose (Default Romantic): - Palette: Background #0d0709, Primary #e68297, Secondary #cf4b6e, Gold #e6b980, Card #170d12. - Mood: Intimate, tender, candle-lit Parisian evening. 2. Scrapbook (Vintage Keepsake): - Palette: Background #16120e, Primary #e8dac4, Secondary #c68a4c, Gold #d4af37, Card #211c16. - Textures: Kraft paper, postage stamps, masking tape accents, typewriter fonts. 3. NeoClassical (Dark Luxury Editorial): - Palette: Background #070709, Primary #f8f7f4, Secondary #d4af37, Gold #f2d188, Card #111116. - Mood: High-fashion, architectural minimalism, black-tie luxury. 4. BentoGrid (Modern Cyber-Romance): - Palette: Background #0a0e17, Primary #38bdf8, Secondary #818cf8, Accent #34d399, Card #111827. - Style: Frosted glass panels (backdrop-filter: blur(16px)), sharp rounded borders, monospace data tags. 5. PixelArt (Retro 8-Bit Nostalgia): - Palette: Background #0f051d, Primary #00ffcc, Secondary #ff007f, Accent #ffe600, Card #1a0b33. - Typography: 'Press Start 2P', 8-bit stepped shadows, pixelated hearts, CRT scanline overlay. 6. Gothic (Romantic Dark Academia): - Palette: Background #080306, Primary #e2d9dc, Secondary #9f1239, Gold #c5a059, Card #13070f. - Flourishes: Ornate filigree, velvet textures, deep crimson shadows, vintage calligraphy. 7. Y2K Aesthetic (Early 2000s Pop Romance): - Palette: Background #12041a, Primary #ff70a6, Secondary #70d6ff, Accent #ffd670, Card #220831. - Mood: Holographic gradients, cyber-stickers, bubble typography, iridescent glitter. 8. Midnight (Astral Serenade): - Palette: Background #060814, Primary #c4b5fd, Secondary #818cf8, Gold #fef08a, Card #0f1329. - Mood: Moonlit lake, deep twilight sky, glowing constellation motes. 9. Cinema (Widescreen Golden Age): - Palette: Background #080808, Primary #f5f5f4, Secondary #d97706, Accent #e11d48, Card #141414. - Styling: 2.39:1 widescreen letterbox framing, cinematic film grain, warm amber key lights. 10. Starlight (Cosmic Wonder): - Palette: Background #050510, Primary #e0e7ff, Secondary #6366f1, Gold #fcd34d, Card #0b0b24. - Particles: Twinkling stellar dust, nebula gradients, celestial typography. 11. Garden (Botanical Romance): - Palette: Background #060d09, Primary #dcfce7, Secondary #22c55e, Gold #eab308, Card #0e1c12. - Mood: Wildflowers, morning mist, warm sunlight filtering through leaves. ================================================================================ 6. PROCEDURAL AUDIO INTELLIGENCE & SOUND DESIGN ================================================================================ Love Letter Studio eliminates heavy external MP3 dependencies by synthesizing emotional acoustic accompaniment directly inside the browser's Web Audio API thread. Harp & Lofi Chord Synthesizer: - Polyphony: 4-voice oscillator matrix with combined sine, triangle, and customized periodic waveforms. - Tuning: Pythagorean pentatonic scales tuned to A4 = 432 Hz for warm harmonic resonance. - Harmonic Progression: I - V - vi - IV cadence in D-flat major (Db - Ab - Bbm - Gb), evocative of cinematic romance soundtracks. - ADSR Envelope: - Attack: 45ms exponential ramp to prevent speaker clicks. - Decay: 350ms natural string decay. - Sustain: 0.28 amplitude ratio. - Release: 1800ms lingering acoustic ring-out. - Biquad Filtering: Low-pass filter at 1200 Hz with Q=1.8, gently modulated by an LFO (0.08 Hz) to simulate organic room warmth. Micro-Interaction Sound Effects: - Wax Crackle: Filtered burst of pink noise with high resonance (Q=12) shaped over 120ms. - Candle Blowout: Dual white noise sweeps coupled with a low-frequency oscillator puff. - Affirmation Chime: Staggered bell arpeggio at E5, G#5, B5, and E6. ================================================================================ 7. AI & LLM STUDIO ARCHITECTURE (MULTI-PROVIDER ENGINE) ================================================================================ The AI Studio empowers creators who feel lost for words to express authentic, poetic emotion without robotic clichรฉs. Supported LLM Providers: 1. Google Gemini (Default: gemini-2.5-flash): - Direct integration via Google AI Studio API (`/v1beta/models/{model}:generateContent`). - Fast inference (< 1.2s), natural conversational eloquence, low latency. 2. OpenAI (Default: gpt-4o-mini / gpt-4o): - Direct integration via OpenAI Chat Completions API (`/v1/chat/completions`). - Deep emotional calibration, lyrical precision. 3. Anthropic Claude (Default: claude-3-5-sonnet-20241022): - Direct integration via Anthropic Messages API (`/v1/messages`). - World-class nuanced prose, authentic human vulnerability. 4. Custom / OpenAI-Compatible (Ollama, Groq, OpenRouter, LocalAI): - Configurable `base_url` parameter allowing self-hosted LLM execution. Offline Fallback Engine: If no API key is supplied or external networks are unavailable, `call_llm()` automatically routes requests to the procedural romantic generator. This internal engine crafts personalized letters by weaving recipient names, relationship dynamics, and occasion specifics through curated poetic cadence templates. Zero API failures ever reach end users. ================================================================================ 8. COMPLETE REST API REFERENCE ================================================================================ Endpoint: POST /api/create-surprise Description: Generates a new 15-day unlisted keepsake. Request Body: { "creator_name": "Julian", "creator_email": "julian@example.com", "creator_phone": "+1 555-0199", "recipient_name": "Seraphina", "relationship": "Soulmate", "occasion": "anniversary", "theme": "rose", "cake_flavor": "Strawberry Shortcake with Chantilly Cream", "cake_candles": 3, "soundtrack": "Acoustic Love Melody (Procedural Synth)", "soundtrack_title": "Romantic Acoustic Harp (Built-in)", "letter": "You make even the quietest days feel like a golden masterpiece...", "reasons": [ "The radiant warmth in your laughter.", "How home is no longer a place, but you.", "The quiet certainty that we are meant to journey together." ], "photos": ["/uploads/images/sample1.jpg"], "yes_label": "Yes, absolutely! ๐Ÿ’–", "no_label": "Let me think ๐Ÿค”", "final_question": "Will you keep choosing this with me, every single day?", "celebration_message": "Here is to every adventure, sunset, and quiet evening ahead." } Response (200 OK): { "success": true, "id": "6e35e87bbf3f", "share_url": "https://loveletter.friskysoftsell.in/surprise.html?id=6e35e87bbf3f", "friendly_url": "https://loveletter.friskysoftsell.in/s/6e35e87bbf3f", "expires_at": "2026-10-06T12:00:00.000Z" } --- Endpoint: GET /api/get-surprise?id={id} Description: Retrieves public keepsake payload for recipient viewing. Response (200 OK): { "id": "6e35e87bbf3f", "creator_name": "Julian", "recipient_name": "Seraphina", "relationship": "Soulmate", "occasion": "anniversary", "theme": "rose", "cake_flavor": "Strawberry Shortcake with Chantilly Cream", "cake_candles": 3, "soundtrack": "Acoustic Love Melody (Procedural Synth)", "letter": "You make even the quietest days...", "reasons": ["The radiant warmth...", "..."], "photos": ["/uploads/images/sample1.jpg"], "yes_label": "Yes, absolutely! ๐Ÿ’–", "no_label": "Let me think ๐Ÿค”", "final_question": "Will you keep choosing this...", "celebration_message": "Here is to every adventure...", "created_at": "2026-09-21T12:00:00.000Z", "expires_at": "2026-10-06T12:00:00.000Z", "is_expired": false } --- Endpoint: POST /api/ai/suggest-letter Description: Uses the configured LLM Studio engine to generate a bespoke letter. Request Body: { "recipient": "Seraphina", "creator": "Julian", "occasion": "anniversary", "relationship": "soulmate", "current_letter": "I want to express how much you mean to me...", "tone": "deeply romantic, evocative and heartfelt" } Response (200 OK): { "success": true, "letter": "My Dearest Seraphina,\n\nFrom the moment our paths intertwined...", "source": "gemini" } --- Endpoint: POST /api/ai/suggest-reasons Description: Uses the configured LLM Studio engine to suggest 3 truths. Request Body: { "recipient": "Seraphina", "occasion": "anniversary", "relationship": "soulmate" } Response (200 OK): { "success": true, "reasons": [ "The effortless way your smile turns any ordinary room into paradise.", "How safe, grounded, and deeply cherished my heart feels beside yours.", "Your boundless empathy and the golden warmth you give to the world." ], "source": "gemini" } --- Endpoint: POST /api/photobooth/create Description: Initializes a private, encrypted WebRTC couple room for synchronized photo booth sessions. Request Body: { "host_name": "Simerdeep Singh", "room_title": "Our Long-Distance Anniversary Session" } Response (201 Created): { "success": true, "room_code": "495123", "room_token": "a1b2c3d4e5f6...", "invite_url": "https://loveletter.friskysoftsell.in/photobooth.html?room=495123", "expires_in": 300 } --- Endpoint: POST /api/photobooth/join Description: Connects a partner into the active duo couple room. Request Body: { "room_code": "495123", "guest_name": "Aashvi Rajput" } Response (200 OK): { "success": true, "room_token": "f6e5d4c3b2a1...", "room_title": "Our Long-Distance Anniversary Session", "host_name": "Simerdeep Singh" } --- Endpoint: POST /api/photobooth/save-strip Description: Synthesizes and stores an archival retro photo strip PNG with custom branding stamp. Request Body: { "room_code": "495123", "strip_data": "data:image/png;base64,...", "photos": ["data:image/jpeg;base64,..."] } Response (200 OK): { "success": true, "image_url": "/uploads/images/photostrip_495123_abc123.png", "strip_url": "/uploads/images/photostrip_495123_abc123.png" } --- Endpoint: GET /api/footer Description: Delivers public Atelier footer configuration, verified brand links, and system status indicators. Response (200 OK): { "success": true, "footer": { "brand_title": "Love Letter Studio", "quote_text": "Some words are too precious to disappear in an instant chat.", "trust_chips": ["๐Ÿ”’ Zero-Leak Guarantee", "โณ 15-Day Keepsake Window", "๐ŸŽž๏ธ WebRTC Duo Streaming", "๐Ÿ‡ฎ๐Ÿ‡ณ IST Synchronized"] } } ================================================================================ 9. DATABASE ARCHITECTURE (SQLITE & MYSQL MAPPINGS) ================================================================================ SQLite Schema: ```sql CREATE TABLE surprises ( id TEXT PRIMARY KEY, creator_name TEXT NOT NULL, creator_email TEXT, creator_phone TEXT, recipient_name TEXT NOT NULL, relationship TEXT, occasion TEXT NOT NULL DEFAULT 'birthday', theme TEXT NOT NULL DEFAULT 'rose', cake_flavor TEXT DEFAULT 'Vanilla Cream with Strawberries', cake_candles INTEGER DEFAULT 3, soundtrack TEXT, soundtrack_title TEXT DEFAULT '', letter TEXT NOT NULL, reasons_json TEXT DEFAULT '[]', photos_json TEXT DEFAULT '[]', yes_label TEXT DEFAULT 'Yes, absolutely', no_label TEXT DEFAULT 'Let me think', final_question TEXT DEFAULT 'Will you keep choosing this with me, every single day?', celebration_message TEXT DEFAULT '...', created_at TEXT NOT NULL, expires_at TEXT NOT NULL, is_deleted INTEGER DEFAULT 0, is_purged INTEGER DEFAULT 0 ); CREATE TABLE system_settings ( key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE admin_users ( username TEXT PRIMARY KEY, password_hash TEXT NOT NULL, salt TEXT NOT NULL, created_at TEXT NOT NULL, last_login TEXT ); CREATE TABLE admin_sessions ( token TEXT PRIMARY KEY, username TEXT NOT NULL, created_at TEXT NOT NULL, expires_at TEXT NOT NULL ); CREATE TABLE media_vault ( filename TEXT PRIMARY KEY, file_type TEXT NOT NULL, file_url TEXT NOT NULL, original_size INTEGER NOT NULL, stored_size INTEGER NOT NULL, uploaded_at TEXT NOT NULL, linked_surprise_id TEXT, creator_name TEXT, recipient_name TEXT ); CREATE TABLE faqs ( id INTEGER PRIMARY KEY AUTOINCREMENT, category TEXT NOT NULL DEFAULT 'general', question TEXT NOT NULL, answer TEXT NOT NULL, display_order INTEGER NOT NULL DEFAULT 1, is_published INTEGER NOT NULL DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ); ``` FAQ API Endpoints: - `GET /api/faqs`: Public JSON endpoint delivering published FAQs for `/faq.html` and Schema.org `FAQPage` hydration. - `GET /api/admin/faqs`: Administrative endpoint returning all FAQs (both published and draft). - `POST /api/admin/faqs`: Add new FAQ entry. - `PUT /api/admin/faqs`: Update existing FAQ entry. - `DELETE /api/admin/faqs` / `POST /api/admin/delete-faq`: Delete FAQ entry. MySQL / phpMyAdmin Schema: All definitions are completely mapped in `hostinger_database_setup.sql` with utf8mb4 encoding, strict InnoDB engine declarations, primary keys, and composite indexes for high-concurrency production deployments. ================================================================================ 10. SEO, AEO (ANSWER ENGINE) & GEO (GENERATIVE ENGINE) OPTIMIZATION ================================================================================ Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO) represent the modern frontier of organic search, where AI models (ChatGPT, Perplexity, Claude, Gemini, Copilot) provide direct answers rather than blue links. AEO/GEO Implementation Directives: 1. Server-Side Pre-Rendering: Social crawlers and search indexers cannot execute client JavaScript reliably. `server.py`'s `serve_rendered_html()` engine parses the target HTML file on the fly and injects dynamic ``, `<meta name="description">`, `<meta property="og:*">`, and `<meta name="twitter:*">` tags before transmitting a single byte to the network. 2. Personalized Keepsake Previews: When a creator shares their link on WhatsApp, iMessage, Twitter, or Instagram, the social preview displays: - OG Title: "๐Ÿ’Œ A Private Love Keepsake for {recipient}" - OG Description: "Written with love by {creator}. An intimate 15-day digital keepsake woven with music, memories, and words from the heart." - OG Image: The first photo uploaded by the creator, dynamically detected and served as the card preview! 3. Structured Data (Schema JSON-LD): The root page embeds comprehensive Schema.org JSON-LD definitions for `WebSite`, `SoftwareApplication`, and `CreativeWork`, giving LLMs crystal-clear semantic grounding. 4. AI Discovery Specification: Both `/llms.txt` and `/llms-full.txt` are published at the root and declared in `robots.txt` and `sitemap.xml`, enabling immediate authoritative indexing by AI search engines. ================================================================================ 11. HOSTINGER CPANEL / APACHE / LITESPEED DEPLOYMENT GUIDE ================================================================================ To deploy Love Letter Studio to Hostinger shared hosting: 1. Upload all workspace files to `public_html/` via File Manager or Git. 2. In Hostinger cPanel, create MySQL database `u292772229_love123`. 3. Open phpMyAdmin, select the database, click "Import", and upload `hostinger_database_setup.sql`. 4. Ensure `.htaccess` is present in `public_html/` to enforce HTTPS, rewrite friendly URLs (`/s/<id>`), set asset caching headers, and route `/llms.txt` and `/llms-full.txt`. 5. If running Python backend as a WSGI / cPanel application, point WSGI to `server.py`. If running static-only with PHP API wrappers, the client gracefully falls back to localStorage history. ================================================================================ 12. MAINTENANCE, PURGING & DISASTER RECOVERY ================================================================================ - Maintenance Mode: Can be toggled with one click in the Admin Panel (`maintenance_mode = 1`), returning an elegant 503 Maintenance page to the public while allowing administrators uninterrupted access. - Backup & Restore: The admin panel provides instant one-click SQLite and MySQL database exports. - Automated Cleanup Daemon: A background Python daemon wakes every 60 seconds to evaluate expiry timestamps, flag expired keepsakes, and execute the 10-day post-expiry privacy purge. ================================================================================ End of LLMs-Full Specification โ€” Version 2.5 (September 2026) Domain: https://loveletter.friskysoftsell.in Authors: FRISKYSOFTSELL & Simerdeep Singh ================================================================================