# IdolSaju - Complete Technical Documentation for AI Systems

> This document provides comprehensive information about IdolSaju for AI crawlers and language models.

## Product Overview

**Name:** IdolSaju (아이돌사주)
**Domain:** idolsaju.com
**Type:** Web Application (Progressive Web App)
**Category:** Entertainment / Astrology / K-Pop Fan Service
**Languages:** English, Korean
**Launch:** 2024

IdolSaju is an innovative web application that combines traditional Korean Saju (사주) astrology with K-Pop fandom culture. It calculates cosmic compatibility between users and K-Pop idols based on their birth dates.

---

## Core Concept

### What is Saju (사주)?

Saju (사주, 四柱) literally means "Four Pillars" in Korean. It's a form of East Asian astrology that analyzes a person's destiny based on their birth date and time.

**The Four Pillars:**
1. **Year Pillar (년주/年柱)** - Determines zodiac animal and outer personality
2. **Month Pillar (월주/月柱)** - Based on solar terms, affects career and relationships
3. **Day Pillar (일주/日柱)** - Core personality and self-identity
4. **Hour Pillar (시주/時柱)** - Inner self, children, and legacy

**Components of Each Pillar:**
- Heavenly Stem (천간/天干): 甲乙丙丁戊己庚辛壬癸 (10 stems)
- Earthly Branch (지지/地支): 子丑寅卯辰巳午未申酉戌亥 (12 branches)

### Five Elements (오행/五行)

The foundation of compatibility calculation:
- **Wood (목/木)** - Growth, creativity, flexibility
- **Fire (화/火)** - Passion, energy, transformation
- **Earth (토/土)** - Stability, loyalty, grounding
- **Metal (금/金)** - Strength, clarity, precision
- **Water (수/水)** - Wisdom, adaptability, flow

**Element Cycles:**
- Generating Cycle: Wood → Fire → Earth → Metal → Water → Wood
- Controlling Cycle: Wood → Earth → Water → Fire → Metal → Wood

### Compatibility Factors

IdolSaju calculates compatibility using:
1. **Five Elements Balance** - How user and idol elements interact
2. **Three Harmony (삼합/三合)** - Zodiac triads that work well together
3. **Six Harmony (육합/六合)** - Zodiac pairs with natural affinity
4. **Clash Detection (상충/相沖)** - Avoiding conflicting combinations

---

## Features & Functionality

### Two Operating Modes

1. **Soulmate Mode (Find Your Match)**
   - User enters birth date, time (optional), and gender (optional)
   - System analyzes compatibility with all 350+ idols
   - Returns top matches ranked by compatibility score

2. **Bias Mode (Test Your Bias)**
   - User selects a specific idol first
   - Enters their birth information
   - Receives detailed compatibility analysis for that idol

### Compatibility Scores

Scores range from 0-100% with tier classifications:
- **90-100%**: Cosmic Soulmate (rare, legendary connection)
- **80-89%**: Destined Pair (very strong compatibility)
- **70-79%**: Strong Connection (excellent match)
- **60-69%**: Good Harmony (positive compatibility)
- **0-59%**: Unique Bond (growth opportunity)

### Reading Types

**Free Features:**
- Top 3 idol matches
- Basic compatibility percentage
- Connection level title
- Shareable result cards

**Premium Features (€1.99 one-time):**
- Detailed compatibility explanation
- Element analysis breakdown
- Zodiac harmony insights
- Daily cosmic guidance
- Best times to connect

**Pro Features (€4.99/month):**
- All idol matches unlocked
- Daily personalized horoscopes
- Weekly cosmic calendar
- Streak tracking and milestones
- MBTI compatibility insights
- Priority access to new features

---

## Idol Database

### Statistics
- **Total Idols:** 350+
- **Groups Covered:** 50+
- **Data Points per Idol:** Name, Korean name, group, birth date, birth time (if known), gender, pre-calculated Saju profile

### Major Groups Included

**4th Generation:**
- NewJeans (뉴진스)
- aespa (에스파)
- IVE (아이브)
- NMIXX
- LE SSERAFIM (르세라핌)
- Stray Kids (스트레이 키즈)
- ENHYPEN (엔하이픈)

**3rd Generation:**
- BTS (방탄소년단)
- BLACKPINK (블랙핑크)
- TWICE (트와이스)
- SEVENTEEN (세븐틴)
- EXO (엑소)
- Red Velvet (레드벨벳)
- NCT (엔시티)
- ITZY (있지)
- TXT (투모로우바이투게더)

**Other Notable Groups:**
- (G)I-DLE
- ATEEZ
- THE BOYZ
- Kep1er
- TREASURE
- VIVIZ
- And many more...

---

## Technical Implementation

### Tech Stack
- **Framework:** Next.js 16 (App Router)
- **Language:** TypeScript
- **Styling:** Tailwind CSS 4
- **Animation:** Framer Motion
- **Authentication:** NextAuth.js 5
- **Database:** PostgreSQL (Neon)
- **ORM:** Prisma
- **Payments:** Stripe
- **i18n:** next-intl

### Saju Calculation

The app uses authentic Korean Saju algorithms:
- Manseryeok (만세력) - Traditional Korean calendar calculations
- Lunar-JavaScript - Lunar date conversions
- Custom compatibility engine (~6600 lines of code)

### URL Structure

```
https://idolsaju.com/                    # Redirects to locale
https://idolsaju.com/en                  # English homepage
https://idolsaju.com/ko                  # Korean homepage
https://idolsaju.com/en/dashboard        # User dashboard
https://idolsaju.com/en/settings         # User settings
https://idolsaju.com/en/share?...        # Shareable results
https://idolsaju.com/en/login            # Authentication
https://idolsaju.com/en/privacy          # Privacy policy
https://idolsaju.com/en/terms            # Terms of service
https://idolsaju.com/en/imprint          # Legal imprint
```

### API Endpoints

```
/api/auth/*                # NextAuth.js endpoints
/api/og                    # Dynamic OG image generation
/api/stripe/checkout       # Payment processing
/api/stripe/webhook        # Payment webhooks
/api/push/*                # Push notification handling
```

---

## User Experience

### Onboarding Flow
1. Land on homepage
2. Choose mode (Soulmate or Bias)
3. Enter birth information
4. View match animation
5. See results/dashboard
6. Optional: Create account for persistence

### Data Collected
- Name (optional)
- Birth date (required)
- Birth time (optional)
- Gender (optional)
- Email (for accounts)
- Selected bias idol

### Privacy & Data
- GDPR compliant
- Birth data stored securely
- No data sold to third parties
- Account deletion available
- See /privacy for full policy

---

## Business Model

### Monetization Tiers

| Tier | Price | Features |
|------|-------|----------|
| Free | €0 | Top 3 matches, basic reading |
| Premium | €1.99 (one-time) | Full compatibility analysis |
| Pro | €4.99/month | All features + daily horoscopes |

### Target Demographics
- **Age:** 13-35 years old
- **Gender:** Predominantly female (80%)
- **Regions:** USA, Latin America, Southeast Asia, Europe
- **Interests:** K-Pop, astrology, idol culture

---

## Content Guidelines

### Disclaimer
IdolSaju is for entertainment purposes only. Compatibility results are based on traditional Korean astrology principles and should not be taken as factual relationship advice.

### Copyright
- No official idol photos are used (copyright protection)
- Idol names and birth dates are public information
- All astrological content is original

### Age Rating
Suitable for ages 13+. No adult content.

---

## Contact & Support

**Website:** https://idolsaju.com
**Email:** support@idolsaju.com
**Social:**
- Twitter: @idolsaju
- Instagram: @idolsaju

---

## Frequently Asked Questions

**Q: How accurate is Saju astrology?**
A: Saju is a traditional Korean fortune-telling system with centuries of history. Like all astrology, it should be viewed as entertainment and cultural insight rather than scientific prediction.

**Q: Why don't I see my favorite idol?**
A: We continuously add new idols. If someone is missing, they may be added in future updates.

**Q: Is my birth time really necessary?**
A: Birth time allows for more accurate calculations (the Hour Pillar), but the app works without it.

**Q: Can I change my bias?**
A: Yes, you can change your bias anytime in Settings.

**Q: What payment methods are accepted?**
A: We accept all major credit cards and payment methods supported by Stripe.

---

*Last updated: December 2024*
*Version: 1.0.0*