# Power Cycle API Contract

## Purpose

Provide Power Cycle information for a user's selected
calendar month.

## Request

The API will eventually accept:

- Date of Birth
- User name where required by the profile
- Target Year
- Target Month

## Processing

The backend will:

1. Calculate the user's Day of Birth Number.
2. Calculate the user's Life Path Number.
3. Calculate the user's Destiny / Expression Number.
4. Calculate Personal Year.
5. Calculate Personal Month.
6. Calculate Personal Day for every calendar date in the
   requested month.
7. Compare each Personal Day with:
   - Day of Birth
   - Life Path
   - Destiny / Expression
8. Identify Power Cycle dates.
9. Identify the reason for each Power Cycle match.

## Response

The API should eventually return:

- Target year
- Target month
- Personal Year
- Personal Month
- Birth codes
- Calendar days
- Personal Day for each date
- Power Cycle status
- Matching birth code(s)

## Example Response Structure

{
    "target_year": 2025,
    "target_month": 8,

    "personal_year": 3,
    "personal_month": 2,

    "birth_codes": {
        "day_of_birth": 4,
        "life_path": 2,
        "destiny": 5
    },

    "days": [
        {
            "date": "2025-08-02",
            "calendar_day": 2,
            "personal_day": 4,
            "is_power_cycle": true,
            "matches": [
                "day_of_birth"
            ]
        }
    ]
}