# SignaLove — Complete Documentation for AI Systems
> The world's first love capsule space launcher. Valentine's Day 2026.
> URL: https://signa.love

## Overview

SignaLove is a Valentine's Day 2026 global social experience built as a progressive web application. Users create digital "love capsules" containing meaningful content, then launch them into real orbital trajectories around a hyper-realistic 3D Earth rendered with Three.js and WebGL. The application combines real satellite physics (via satellite.js TLE data), browser-based augmented reality (via LocAR.js), and Valentine's Day themed social sharing.

## Core Concepts

### Love Capsules
A love capsule is a sealed digital payload containing one of four content types:
- **Link**: A meaningful website URL (e.g., a shared memory, favorite article, or special place)
- **Photo**: An uploaded image (stored securely in cloud storage)
- **Song**: A music link (Spotify, Apple Music, YouTube, SoundCloud, etc.)
- **Note**: A text-based love letter or message

Each capsule includes:
- A title (visible on the globe and in AR)
- An optional personal message
- An optional recipient name and email
- Orbital parameters: inclination (0-90°), RAAN (0-360°), altitude (200-2000km)
- Auto-generated TLE (Two-Line Element) data for realistic orbital propagation
- A unique Valentine's-branded QR code
- View and open counters

### Orbital Mechanics
Capsules follow authentic orbital mechanics powered by satellite.js:
- **Inclination**: The angle between the orbital plane and Earth's equator (0° = equatorial, 90° = polar)
- **RAAN (Right Ascension of Ascending Node)**: Determines where the orbital plane intersects the equator
- **Altitude**: The height above Earth's surface in kilometers
- Each capsule has TLE line1 and line2 data for precise position calculation at any time

### Discovery Methods
Users can discover capsules through three methods:
1. **3D Globe**: Interactive WebGL Earth showing all active capsules orbiting in real-time. Click any capsule to view it.
2. **AR Sky Viewer**: Browser-based augmented reality. Uses phone camera, GPS, and gyroscope to display capsules at their actual orbital positions above the user.
3. **QR Code**: Each capsule generates a unique QR code that can be printed on cards, included in bouquets, or shared digitally.

## Features In Detail

### 3D Earth Globe (Homepage)
- Hyper-realistic Earth rendered with Three.js and React Three Fiber
- 8K day texture, 4K night texture, 4K specular map, 2K cloud layer
- Real-time atmosphere shader
- Starfield with procedural Milky Way
- All active capsules render as glowing orbital trails
- Hover tooltips show capsule title, author, and launch time
- Click-to-navigate to capsule detail page

### AR Sky Viewer (/ar)
- Browser-based AR using LocAR.js (no app download)
- Requires: camera permission, GPS permission, gyroscope
- Calculates look angles to all orbiting capsules from user's GPS position
- Displays capsules as glowing markers in the real sky
- Tap to select, then open to view capsule contents
- Records discovery events with location data

### Launch Wizard (/launch)
- Step 1: Payload — choose type, add content, title, message, optional recipient
- Step 2: Orbit — customize inclination, RAAN, altitude with visual sliders
- Step 3: Launch — cinematic launch animation, capsule enters orbit
- Includes launch limits (configurable per-user max)
- Optional Valentine's email delivery to recipient

### Capsule View (/capsule/:id)
- Cinematic reveal animation
- Displays payload content based on type
- Shows author info, launch time, view/open counts
- Share button with QR code and link copying
- Discovery logging (AR, globe, or QR)

### User Profile (/profile)
- Display name and bio (editable)
- Capsules launched count and list
- Capsules discovered count and list
- QR code generation for each capsule

### PWA Support
- Installable as progressive web app on iOS, Android, and desktop
- Offline support with cached assets
- Full-screen standalone mode

## Frequently Asked Questions

### What is SignaLove?
SignaLove is the world's first love capsule space launcher — a Valentine's Day 2026 experience where you launch digital love messages into real orbital trajectories around Earth and discover them via AR.

### Is SignaLove free?
Yes, completely free. Create capsules, use AR, generate QR codes, send Valentine's emails — all at no cost.

### What devices does it work on?
Any modern smartphone (iOS/Android) with a web browser. Desktop browsers support the 3D globe. AR requires a phone with camera, GPS, and gyroscope.

### Do I need to download an app?
No. SignaLove runs entirely in your web browser. You can optionally install it as a PWA for the best experience.

### How does the AR sky viewer work?
It uses your phone's camera, GPS, and gyroscope to calculate which capsules orbit overhead, then displays them as glowing markers in augmented reality.

### Can I send a capsule to someone specific?
Yes — add their name and email during launch. They'll receive a Valentine's email with a direct link. You can also share a QR code.

### What happens to my capsule after Valentine's Day?
Capsules remain in orbit indefinitely on the globe and continue to be discoverable.

### Is my data private?
Camera and GPS are used only for the AR experience. No location data is stored from the AR viewer. Email addresses are used only for Valentine's delivery.

## Technical Architecture
- **Frontend**: React 18 + TypeScript + Vite + Tailwind CSS
- **3D Rendering**: Three.js + React Three Fiber + React Three Drei
- **Orbital Mechanics**: satellite.js with TLE data
- **AR**: LocAR.js (browser-based location AR)
- **QR Codes**: react-qrcode-logo
- **Backend**: Lovable Cloud (PostgreSQL + Edge Functions + Storage)
- **Authentication**: OAuth (Google)
- **Animations**: Framer Motion

## URL Structure
| Path | Description | Auth Required |
|------|-------------|---------------|
| / | 3D globe with orbiting capsules + landing overlay | No |
| /features | Feature showcase page | No |
| /docs | How-to guide and device compatibility | No |
| /install | PWA installation instructions | No |
| /launch | Capsule creation wizard | Yes |
| /ar | AR sky viewer | Yes |
| /capsule/:id | Individual capsule viewer | Yes |
| /profile | User dashboard with launched/discovered capsules | Yes |

## Contact & Social
- Website: https://signa.love
- Twitter: @SignaLove