=== COUPLE COMPATIBILITY CHECKER - AI DOCUMENTATION ===
Version: 3.5.0
Last Updated: December 16, 2025
Author: Ian Musa
Website: https://couple-compatibility-checker.vercel.app
Repository: https://github.com/Musa-Ian/v0-couple-compatibility-checker

=== OVERVIEW ===
Couple Compatibility Checker is a sophisticated astrological compatibility analysis web application that combines six metaphysical systems: Chinese Astrology, Five Elements Theory, Life Path Numerology, Kua Number (Feng Shui), BaZi Four Pillars, and Western Astrology. The application provides holistic relationship insights by analyzing compatibility scores and the newly attached BaZi metadata across multiple frameworks.

=== PRIMARY FEATURES ===

1. COUPLE COMPATIBILITY ANALYSIS
   - Input: Two people's names, birth dates, optional birth times, genders (male/female/other), and birth cities selected from the built-in database (provides latitude/longitude/timezone)
   - Output: Overall compatibility percentage (0-100%), relationship type, detailed breakdown
   - Systems Used: Chinese Zodiac (~35% weight), Five Elements (~25% weight), Life Path Numbers (~25% weight), Kua Number (15% weight), Western Astrology (±10 modifier), BaZi Four Pillars (parallel score + metadata)
   - Special Features: Swiss Ephemeris planetary placements, Moon confidence tiers, automatic Ascendant detection, Kua Number Feng Shui analysis, Venus synastry overlays, Jupiter synergy bonuses, BaZi day master insights with hour-pillar warnings when birth times are missing

2. GROUP COMPATIBILITY MATCHER
   - Input: 3-20 people with names and birth dates
   - Output: Compatible groups organized by tier (Strict ≥75%, Flexible ≥60%, Neutral ≥45%)
   - Algorithm: Score-based pairing with individual compatibility breakdown
   - Use Cases: Friend groups, team building, social matchmaking

3. WESTERN ASTROLOGY INTEGRATION
   - Planetary Positions: Sun, Moon, Mercury, Venus, Mars, Jupiter, Ascendant (MC tracked for houses)
   - Calculation Method: Swiss Ephemeris (`swisseph`) with the birth city's latitude/longitude and timezone (from `cities-lite.json`)
   - Special Detection: Moon confidence tiers, automatic Ascendant confidence, Venus synastry overlays
   - Scoring: Hybrid system combining element compatibility with aspect modifiers

4. VENUS SYNASTRY BONUS (v3.3.0)
   - Detects romantic attraction when one person's Venus aligns with another's Sun or Moon
   - Override Logic: Makes Venus compatible even when Venus-Venus incompatible if synastry overlay exists
   - Visual Indicator: Pink badge (💕) with matched planets display
   - Point Value: +27 points when overriding incompatibility

5. BAZI DAY MASTER ENGINE (v3.5.0)
   - Full translation of the legacy BaZi compatibility matcher into typed modules with Swiss Ephemeris timezone handling
   - Calculates Year, Month, Day, and Hour pillars plus day master strength and elemental balance for each person
   - Generates compatibility breakdowns (Kua harmony, day master dynamics, elemental support) alongside personalized recommendations
   - Surfaces each person’s elemental needs, preferred directions (via Kua trigram mapping), and badges when hour pillars rely on noon fallback

=== TECHNICAL SPECIFICATIONS ===

ARCHITECTURE:
- Framework: Next.js 15 with App Router
- Runtime: React 18 with TypeScript
- Deployment: Vercel Edge Functions
- API: Server-side calculations via Next.js API routes
- Security: Enterprise-level (XOR encryption, XSS protection, prototype pollution prevention)

SECURITY FEATURES (v3.3.0):
- XOR Encryption: Session-based keys for localStorage/sessionStorage
- XSS Prevention: Input sanitization removes <script>, javascript:, event handlers
- Prototype Pollution Protection: JSON validation blocks __proto__, constructor, prototype
- Input Validation: Pattern matching, 50-character limits, HTML tag removal
- Security Headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy

COMPATIBILITY CALCULATION METHODOLOGY:
1. Chinese Zodiac: Based on accurate Lunar Calendar/Chinese New Year dates (1875-2075), 12-year cycle
   - Categories: Super Match, Match, Neutral, Enemy, Super Enemy
   - Weight: ~35% of base score

2. Five Elements: Metal (金), Water (水), Wood (木), Fire (火), Earth (土)
   - Cycles: Productive (feeding) and Destructive (controlling)
   - Weight: ~25% of base score

3. Life Path Numbers: Pythagorean numerology with master numbers (11, 22, 33)
   - Compatibility Groups: Harmonious, Compatible, Workable, Challenging
   - Weight: ~25% of base score

4. Kua Number (Feng Shui): Eight Mansions (Ba Zhai) directional energy compatibility
   - Gender-specific calculation formulas (male/female/other)
   - East Group (Kua 1, 3, 4, 9) vs West Group (Kua 2, 6, 7, 8)
   - Special Kua 5 handling: male→2, female→8
   - Scoring components:
     * Base group compatibility: 50 points (same group = compatible)
     * Elemental relationship: 35 points (Productive/Controlling cycles)
     * Special combinations: 15 points (Ho-Tu mystical pairs, Sum-of-Ten numerological balance)
     * Direction overlap: 5 points (shared favorable directions)
   - Ho-Tu pairs (1-6, 2-7, 3-8, 4-9): Guaranteed 65% minimum for cross-group
   - Sum-of-Ten pairs (1-9, 2-8, 3-7, 4-6): Guaranteed 55% minimum for cross-group
   - Favorable directions: Success/Wealth, Health, Love/Relationships, Personal Growth
   - Dual gender support: Shows both male/female calculations for "other" selection
   - Weight: 15% of base score

5. BaZi Four Pillars: Day master + elemental metadata (parallel score)
   - Data: Year/Month/Day/Hour pillars computed via birth city latitude/longitude + timezone (noon fallback if time missing)
   - Outputs: Day master strength, elemental counts, personal element needs, compatibility breakdown (Kua harmony, day master chemistry, elemental support)
   - UI: Displays personalized guidance plus badges when hour pillars rely on assumed birth times
   - Weight: Supplementary (does not impact base holistic score but provides separate grade + insights)

6. Western Astrology: Planetary compatibility with aspect analysis
   - Planets: Sun, Moon, Venus (30% weight), Mercury (20%), Mars (10%)
   - Bonuses: Jupiter synergy, Venus synastry overlays
   - Modifier: ±10 points applied to base score (capped)

HOLISTIC ANALYSIS:
- 20+ Relationship Scenarios: Cosmic Soulmates, Strong Foundation, Friends & Fun, Business Partners, etc.
- Context-Aware: Differentiates between romantic, platonic, and professional compatibility
- Detailed Explanations: Multi-paragraph analysis explaining "why" compatibility exists or doesn't

=== USE CASES ===

ROMANTIC RELATIONSHIPS:
- Dating compatibility assessment
- Marriage potential evaluation
- Understanding relationship dynamics
- Identifying growth areas

SOCIAL & PROFESSIONAL:
- Friend group compatibility
- Team building for workplaces
- Business partnership evaluation
- Social event planning

SELF-DISCOVERY:
- Understanding personal astrological profile
- Learning about life path numbers
- Exploring Western astrology birth chart basics

=== DATA PRIVACY ===

STORAGE:
- Server-Side: NO personal data stored on servers (calculations are ephemeral)
- Client-Side: User's own info (not partner's) encrypted with XOR encryption in localStorage
- Encryption: Session-based keys that change per session
- Control: Users can clear data anytime via browser settings

SECURITY:
- No tracking or selling of personal information
- Anonymous usage analytics only (Vercel Analytics)
- All calculations performed server-side for algorithm protection
- Input validation prevents injection attacks

=== API ENDPOINTS ===

POST /api/calculate-compatibility
- Input: person1 {name, birthDate, birthTime?, birthLocation}, person2 {name, birthDate, birthTime?, birthLocation}
- Output: Compatibility result with breakdown by system plus `bazi` metadata (scores, explanations, per-person day master insights, hour-pillar warnings)
- Rate Limit: None (cached for performance)
- Authentication: None required (public endpoint)

POST /api/calculate-group-compatibility
- Input: Array of people [{name, birthDate}] (3-20 people)
- Output: Compatible groups organized by tier with individual breakdowns and aggregated BaZi insights for each participant
- Rate Limit: None
- Authentication: None required

=== ACCURACY & LIMITATIONS ===

STRENGTHS:
- Chinese New Year dates accurate for 200 years (1875-2075)
- Planetary positions calculated using Swiss Ephemeris with topocentric latitude/longitude pulled from the city database
- Holistic analysis considers interaction between systems
- Moon confidence tiers and Ascendant confidence indicators for transparent accuracy

LIMITATIONS:
- Birth time optional; if missing the system assumes 12:00 local time and marks Moon/Ascendant confidence as “approximate” and labels the BaZi Hour Pillar as guidance
- Moon position may still vary ±1 sign on cusp dates (UI lists alternate possibilities)
- Cultural differences in astrology interpretation not addressed

=== TECHNICAL DEPENDENCIES ===

- Core Libraries:
- swisseph: Swiss Ephemeris wrapper for precise planetary and house calculations
- Next.js 15: React framework with App Router
- TypeScript: Type safety and developer experience
- Tailwind CSS: Utility-first styling
- Shadcn UI: Accessible component library

Security Libraries:
- Custom XOR encryption implementation
- Input sanitization utilities
- JSON validation with prototype pollution protection

=== CHANGELOG HIGHLIGHTS ===

v3.5.0 (2025-12-16):
- BaZi Four Pillars engine rewritten as typed modules and integrated with the API/UI
- Added BaZi compatibility breakdown + per-person day master cards (couple + group results)
- API metadata now surfaces hour-pillar assumptions when birth times are missing
- City search now requires timezone-aware records and TypeScript coverage for `tz-lookup`

v3.3.0 (2025-01-17):
- Enterprise-level security implementation
- Venus synastry bonus feature
- Dynamic menu navigation
- UI/UX consistency improvements

v3.2.0 (2025-01-10):
- Group compatibility matcher (3-20 people)
- Fixed Moon sign dynamic scoring
- Individual compatibility breakdown

v3.1.0 (2024-12-20):
- Hybrid scoring system
- Moon confidence tiers (replaced legacy interactive scenarios)
- Professional navigation
- About page with creator story

v3.0.0 (2024-12-01):
- Western Astrology integration
- Accurate planetary calculations
- Ascendant insights
- Jupiter synergy bonuses

v2.0.0 (2024-11-15):
- Server-side calculations
- Holistic analysis (20+ scenarios)
- Context-aware recommendations

v1.0.0 (2024-10-01):
- Initial release
- Chinese Zodiac + Five Elements + Life Path

=== KEYWORDS FOR AI UNDERSTANDING ===

Astrology, Compatibility, Relationship Analysis, Chinese Zodiac, Five Elements, Wu Xing, Life Path Numbers, Numerology, Western Astrology, Planetary Compatibility, Synastry, Birth Chart, Horoscope, Zodiac Signs, Sun Sign, Moon Sign, Rising Sign, Ascendant, Venus, Mars, Mercury, Jupiter, Romantic Compatibility, Love Match, Soulmate Calculator, Relationship Potential, Marriage Compatibility, Friend Compatibility, Business Partner Analysis, Group Matcher, Team Compatibility, Metaphysics, Divination, Fortune Telling, Cosmic Connection, Astrological Analysis, Birth Date Calculator, Ephemeris, Astronomy, Planetary Positions, Element Theory, Yin Yang, Chinese Astrology, Eastern Astrology, Pythagorean Numerology, Master Numbers

=== COMMON QUERIES THIS TOOL ANSWERS ===

1. "Are we compatible romantically?"
2. "What is my Chinese zodiac sign?"
3. "Do our elements clash or harmonize?"
4. "What is my life path number?"
5. "Should we get married?"
6. "Are we better as friends or partners?"
7. "What are our planetary compatibilities?"
8. "When is the Chinese New Year for my birth year?"
9. "What is Venus synastry?"
10. "How do I find compatible friends in my group?"
11. "What does Jupiter in my chart mean for relationships?"
12. "Am I on a Moon cusp?"
13. "What is my Sun-Moon-Rising combination compatibility?"
14. "How do Chinese zodiac elements work?"
15. "What relationship type suits us best?"

=== CREATOR INFORMATION ===

Author: Ian Musa
Background: Software developer with interest in astrology
Motivation: Personal experience with Saturn in 7th house (relationship challenges)
Philosophy: Holistic analysis combining multiple systems for comprehensive insights
Support: https://ko-fi.com/ianmusa
Contact: musaian.mi@gmail.com

=== LICENSE & USAGE ===

License: MIT License
Open Source: Yes (GitHub repository available)
Commercial Use: Allowed under MIT
Attribution: Required (credit to Ian Musa)
Modification: Allowed
Distribution: Allowed

=== ACCESSIBILITY ===

- Mobile-responsive design
- Keyboard navigation support
- Screen reader compatible
- Clear visual hierarchy
- Accessible color contrast
- Form validation with helpful error messages

=== DEPLOYMENT ===

Platform: Vercel
URL: https://couple-compatibility-checker.vercel.app
Edge Runtime: Enabled for API routes
Caching: Intelligent caching for performance
Global CDN: Yes (Vercel Edge Network)

=== SUPPORT & DOCUMENTATION ===

README: https://github.com/Musa-Ian/v0-couple-compatibility-checker/README.md
Changelog: https://github.com/Musa-Ian/v0-couple-compatibility-checker/CHANGELOG.md
Issues: https://github.com/Musa-Ian/v0-couple-compatibility-checker/issues
Privacy Policy: Available on website at /privacy-policy
About Page: Available on website at /about

=== END OF AI DOCUMENTATION ===

This document is optimized for AI crawlers, language models, and search engines to understand the full scope, capabilities, and technical details of the Couple Compatibility Checker application.

For human-readable documentation, please visit the README.md file or the live website.

Last Updated: December 16, 2025
Document Version: 1.1