# YOD - Find Your Twin Match in Real Life

> Astrology dating and social networking app connecting people through deep astrological compatibility

## Overview

YOD is a revolutionary astrology-based social networking app that helps you find your "twin matches" - people who share your exact sun, moon, and rising signs - in real life. Experience YOD Moments when someone with your identical birth chart configuration is nearby.

## Key Features

### YOD Moments
Real-time proximity notifications when someone with matching sun/moon/rising signs is within 100 meters. The app uses background location tracking to alert you when twin matches are nearby.

### Complete Birth Chart Analysis
- Real-time birth chart calculations powered by Swiss Ephemeris
- Precise astronomical calculations based on exact birth time and location
- Displays sun, moon, and rising signs with beautiful zodiac constellation art
- Updates dynamically as planetary positions change

### Community & Social Features
- **Atrium**: Social feed filtered by astrological compatibility
- See posts from users who share at least one of your major three signs
- Vote and comment on posts
- Share your cosmic perspective with the community

### Love & Dating
- Find romantic matches based on deep astrological compatibility
- Proximity-based matching shows nearby potential partners
- Compatibility scores weighted by sun (40%), moon (40%), and rising (20%)
- See detailed birth chart comparisons

### Profile & Setup
- Comprehensive onboarding captures birth date, time, and location
- Manual location selection via Google Places API
- Profile customization with profile images
- Privacy controls for location sharing

## Technology Stack

- **Frontend**: React Native 0.76.9 with Expo SDK 52
- **Navigation**: expo-router with file-based routing
- **Backend**: Firebase (Firestore, Auth, Storage)
- **Location**: expo-location with background tracking
- **Calculations**: Google Cloud Run service with Swiss Ephemeris
- **Maps**: Google Maps API for location selection
- **State Management**: Context API + Zustand
- **Internationalization**: i18next (English/Latin)

## App Architecture

### Authentication Flow
1. Email/password sign up with verification
2. Onboarding: name → birth details → location permission
3. Birth chart calculation on setup completion
4. Redirect to main app (Atrium tab)

### Location & Matching
- Background location updates every 10 minutes
- Geohash-based proximity queries for efficient matching
- Firestore GeoPoint storage with geohash indexing
- Activity feed notifications for new matches

### Data Models

**User Profile:**
- Basic info: firstName, email, profileImage
- Birth data: birthDate, birthTime, birthLocation (GeoPoint)
- Astrological: signs (sun/moon/rising), geohash
- Privacy: disabled flag, verified flag
- Location: lastKnownLocation, twinFindingEnabled

**Post:**
- Content: text, optional image (Firebase Storage)
- Author: embedded user data with signs
- Engagement: votes (separate collection), comments
- Filtering: Posts shown based on sign matching

**Match:**
- User references and basic info
- Distance calculation
- Compatibility score
- Match type: twin (all 3 signs) or love (compatibility-based)
- Timestamp of discovery

## Design System

### Colors
- Primary: `#21263a` (deep blue)
- Accent: `#f1b424` (gold)
- Background: `#0a0e1a` (near black)
- Muted text: `rgba(255,255,255,0.6)`

### Typography
- Headings: HighTideRegular custom font
- Body: System fonts (SF Pro on iOS, Roboto on Android)

### Component Naming
All components prefixed with "Yod" (e.g., YodButton, YodPost, YodInput)

## Available Now

YOD is live on iOS and Android. Download at https://apps.apple.com/app/yod/id6756529634 or https://play.google.com/store/apps/details?id=com.yod.mrcto

### Upcoming Features
- Event creation for cosmic gatherings
- Enhanced compatibility algorithms
- Transit notifications (when planets align with your chart)
- Group features for connecting multiple cosmic twins

## Download

Visit https://yod-app.com to download YOD and start experiencing YOD Moments.

---

## Technical Documentation

### File Structure
```
app/
  (auth)/          # Authentication flow
  (setup)/         # Onboarding screens
  (tabs)/          # Main app with tab navigation
    atrium/        # Social feed
    folio/         # User profile
services/          # Business logic
  authService.ts
  postService.ts
  matchingService.ts
  locationTrackingService.ts
components/        # Reusable UI (all Yod-prefixed)
context/           # Global state
  authContext.tsx
  themeContext.tsx
  modalContext.tsx
stores/            # Zustand stores
  setupStore.ts
```

### Key Services

**authService.ts:**
- Firebase Authentication integration
- User status checking (verified, disabled, setup complete)
- Sign up/in/out flows
- Account management

**matchingService.ts:**
- Proximity-based matching using geohashes
- Compatibility score calculations
- Activity feed population
- Match discovery and notifications

**locationTrackingService.ts:**
- Background location tracking setup
- Firestore location updates
- Permission handling
- Task manager integration

**postService.ts:**
- Create/read/update posts
- Voting system
- Comment management
- Sign-based filtering

### Environment Variables
- Firebase config (API key, project ID, etc.)
- Google Maps API key
- GCP Swiss Ephemeris endpoint
- Expo project ID

### Deployment
- iOS: TestFlight → App Store
- Android: Internal testing → Google Play
- EAS Build for production builds
- Firebase hosting for web assets

## Privacy & Permissions

### Required Permissions
- **Location**: Always (for background tracking and YOD Moments)
- **Notifications**: Push notifications for matches and activity
- **Camera/Photos**: Profile picture upload

### Data Privacy
- Location data used only for matching
- Exact coordinates never shared with other users
- Only distance and general area shown
- Birth time/location kept private
- Can disable location tracking anytime

### Account Management
- Email verification required
- Account can be disabled (not deleted) by admins
- Password reset available
- Profile data exportable

---

*Last updated: December 2025*