# xpop: Complete Technical Specification, Semantic Ontology & API Guide

## 1. System Overview
- **Name**: xpop
- **Canonical URL**: https://xpop.app
- **License**: Proprietary / Web Service
- **Supported Languages**: English (en), Russian (ru)
- **Tagline (EN)**: Where Music Finds Love — Minimalist Music Dating
- **Tagline (RU)**: Где музыка находит любовь — Минималистичный музыкальный дейтинг

xpop is an online dating platform where romantic compatibility is determined through shared musical tastes, vinyl obsessions, and acoustic affinities rather than superficial photo-swiping. 

---

## 2. Design System: "Airy Powder Minimal"
The user interface follows a distinct, soothing color palette designed for high aesthetic appeal and visual lightness:
- **Silk White**: `#FDFBFB` (clean neutral background)
- **Soft Blush**: `#FAD2E1` (primary warm powder tone)
- **Powder Lilac**: `#E8DFF5` (secondary subtle accent)
- **Powder Peach**: `#FCE1E4` (soft highlight)
- **Primary Rose**: `#E08798` (action buttons, badges, key emphasis)
- **Border Subtle**: `#F1E3E7` (border lines)
- **Text Primary**: `#23232C` (deep contrast charcoal)
- **Text Secondary**: `#6F6F79` (readable body grey)

---

## 3. Mathematical Compatibility Engine (MusicEngine)

### 3.1 Ranked Biased Overlap (RBO)
Given two user top-artist rankings $S = (s_1, s_2, \dots, s_k)$ and $T = (t_1, t_2, \dots, t_m)$, the overlap at depth $d$ is:
$$A_d = \frac{|S_{1:d} \cap T_{1:d}|}{d}$$
The RBO score with persistence parameter $p \in (0, 1)$ (where $p = 0.85$ in xpop) is evaluated as:
$$\text{RBO}(S, T, p) = (1 - p) \sum_{d=1}^{\min(k, m)} p^{d-1} A_d$$

### 3.2 Genre Weighting (Jaccard Index)
Let $G_A$ and $G_B$ be the sets of genres derived from each user's top artists:
$$J(G_A, G_B) = \frac{|G_A \cap G_B|}{|G_A \cup G_B|}$$

### 3.3 Composite Score
The final compatibility score displayed to users (0% to 100%) is calculated as:
$$\text{Score} = \text{round}\left( 0.65 \times \text{RBO} + 0.35 \times J(G_A, G_B) \right) \times 100$$
If the two users share 3 or more artists in their Top 3, an acoustic synergy bonus (+5%) is applied, capped at 99%.

---

## 4. Entity Schemas & JSON Data Structures

### 4.1 UserProfile
```json
{
  "id": "string (uuid)",
  "name": "string",
  "age": "integer (18-99)",
  "gender": "string ('male' | 'female' | 'nonbinary')",
  "seeking": "string ('male' | 'female' | 'all')",
  "city": "string",
  "bio": "string",
  "photo_urls": ["string (url)"],
  "top_artists": [
    {
      "rank": 1,
      "artist_id": "the-cure",
      "artist_name": "The Cure",
      "genre": "Post-Punk"
    }
  ],
  "created_at": 1741755600000
}
```

### 4.2 CompatibilityResult
```json
{
  "score": 94,
  "common_artists": ["The Cure", "Depeche Mode", "Кино"],
  "vibe_summary": "Deep aesthetic sync in 80s Post-Punk & Synthwave",
  "icebreaker": "Ask which track from Disintegration changed their perspective on music"
}
```

### 4.3 VibeCardResponse
```json
{
  "archetype": "Melancholic Post-Punk Romantic / Меланхоличный Пост-Панк Романтик",
  "vibe_title": "Vintage Melancholy & Rainy Neon Lights / Винтажная меланхолия и дождливые огни",
  "vibe_description": "You find deep beauty in minor chords, dark velvet, and night walks. / Ты находишь глубокую красоту в минорных аккордах, сером бархате и ночных прогулках.",
  "top_genres": ["Post-Punk", "Darkwave", "Soviet Wave"],
  "color_gradient": ["#E08798", "#E8DFF5"],
  "match_rarity": "Rare taste: matches 14% of profiles / Редкий вкус: совпадение с 14% анкет"
}
```

---

## 5. Bilingual Localization Architecture
xpop implements reactive real-time language toggling without requiring a full page reload:
- State Management: `LocaleService` singleton with `ValueNotifier<String>` ('ru' | 'en').
- Autodetection: Reads `ui.PlatformDispatcher.instance.locale.languageCode`.
- UI Re-rendering: Wrapped in top-level `ValueListenableBuilder`.
- URL Query Param Support: `?lang=en` or `?lang=ru` overrides auto-detection.
- Backend Support: All API endpoints accept optional `?lang=en` / `?lang=ru` queries.

---

## 6. Image Optimization Architecture
All user-uploaded photos are client-side and server-side compressed to strictly under **100 KB**:
- JPEG quality downsampling with adaptive iterative reduction.
- Max resolution clamped to 1280x1280.
- Strips EXIF metadata for user privacy and bandwidth conservation.
- Guarantees sub-100ms photo load speeds on mobile networks.

---

## 7. Contact & Links
- Website: https://xpop.app
- Sitemap: https://xpop.app/sitemap.xml
- Robots Directive: https://xpop.app/robots.txt
- Machine Readable Entry: https://xpop.app/llms.txt