# Astrology Chart API

A comprehensive REST API for managing astrological birth charts with professional-grade calculations, built with Node.js, Express, TypeScript, and Prisma. This API provides complete astrological chart generation including planetary positions, house systems, and aspect calculations.

## 🚀 Features

- **Complete CRUD Operations**: Create, read, update, and delete astrology charts
- **Advanced Astrological Calculations**:
  - Automatic sun sign, moon sign, and rising sign calculations
  - Planetary positions for all 10 major celestial bodies
  - 12-house system with accurate cusp calculations
  - Comprehensive aspect analysis between planets
  - Professional-grade astrological algorithms
- **Detailed Chart Data**:
  - Planetary positions with degrees, signs, and houses
  - Retrograde motion detection
  - Aspect calculations with orb precision
  - House cusp positions and interpretations
- **User Management**: Secure user authentication and authorization
- **Admin Controls**: Moderation, verification, and approval system
- **Public Sharing**: Option to make charts public for community viewing
- **Advanced Filtering**: Search by chart type, astrological signs, and date ranges
- **Statistics & Analytics**: Comprehensive chart statistics and insights
- **Rate Limiting**: Built-in protection against abuse
- **Input Validation**: Comprehensive validation and sanitization
- **Error Handling**: Detailed error messages and logging
- **Professional Interpretations**: AI-generated chart interpretations with astrologer notes
- **Redis Caching**: High-performance caching for chart data and calculations
- **Session Management**: Secure session handling with Redis

## 🏗️ Architecture

The API follows a clean, layered architecture with comprehensive separation of concerns:

```text
src/
├── controllers/AstrologyChart/
│   ├── AstrologyChartController.ts    # HTTP request handling & response formatting
│   ├── AstrologyChartService.ts       # Business logic & validation
│   └── AstrologyChartRepository.ts    # Data access & Prisma operations
├── routes/astrologyChart/
│   └── index.ts                       # Route definitions & middleware
├── middleware/
│   ├── astrologyChartValidation.ts    # Input validation & sanitization
│   ├── requireAuth.ts                 # JWT authentication
│   └── redisMiddleware.ts             # Redis caching middleware
├── lib/
│   ├── prisma.ts                      # Prisma client configuration
│   └── redis.ts                       # Redis client configuration
├── types/
│   └── astrology.ts                   # TypeScript interfaces & enums
└── utils/
    ├── asyncHandler.ts                # Async error handling
    ├── errorHandler.ts                # Global error handling
    └── uniResponse.ts                 # Standardized response format
```

## 📋 API Endpoints

### Public Endpoints (No Authentication Required)

| Method | Endpoint                                    | Description                 |
| ------ | ------------------------------------------- | --------------------------- |
| `GET`  | `/v1/astrology-charts/public`               | Get public astrology charts |
| `GET`  | `/v1/astrology-charts/search/sign/:sunSign` | Search charts by sun sign   |
| `GET`  | `/v1/astrology-charts/health`               | Health check                |

### Authenticated Endpoints (User Authentication Required)

| Method   | Endpoint                                            | Description                                             |
| -------- | --------------------------------------------------- | ------------------------------------------------------- |
| `POST`   | `/v1/astrology-charts`                              | Create a new astrology chart                            |
| `GET`    | `/v1/astrology-charts/user`                         | Get user's astrology charts                             |
| `GET`    | `/v1/astrology-charts/:chartId`                     | Get specific chart by ID                                |
| `PUT`    | `/v1/astrology-charts/:chartId`                     | Update an astrology chart                               |
| `DELETE` | `/v1/astrology-charts/:chartId`                     | Delete an astrology chart                               |
| `POST`   | `/v1/astrology-charts/:chartId/interpretation`      | Generate chart interpretation                           |
| `GET`    | `/v1/astrology-charts/:chartId/detailed`            | Get detailed chart with planetary positions and aspects |
| `GET`    | `/v1/astrology-charts/:chartId/planetary-positions` | Get planetary positions for a specific chart            |
| `GET`    | `/v1/astrology-charts/:chartId/aspects`             | Get aspects for a specific chart                        |

### Admin Endpoints (Admin Authentication Required)

| Method | Endpoint                                | Description                       |
| ------ | --------------------------------------- | --------------------------------- |
| `GET`  | `/v1/astrology-charts`                  | Get all charts with admin filters |
| `GET`  | `/v1/astrology-charts/statistics`       | Get chart statistics              |
| `POST` | `/v1/astrology-charts/:chartId/verify`  | Verify a chart                    |
| `POST` | `/v1/astrology-charts/:chartId/approve` | Approve a chart                   |

## 🔐 Authentication

The API uses JWT-based authentication with role-based access control:

- **Public**: No authentication required
- **User**: Valid JWT token required
- **Admin**: Valid JWT token with admin role required

## 📊 Data Models

### AstrologyChart

```typescript
interface AstrologyChart {
  id: string;
  userId: string;
  birthDate: Date;
  birthTime?: string;
  birthLocation: string;
  latitude?: number;
  longitude?: number;
  timezone?: string;
  sunSign: string;
  moonSign?: string;
  risingSign?: string;
  chartType: ChartType;

  isApproved: boolean;
  chartInterpretation?: string;
  astrologerNotes?: string;
  createdAt: Date;
  updatedAt: Date;
  planetaryPositions: PlanetaryPosition[];
  houseCusps: HouseCusp[];
}
```

### PlanetaryPosition

```typescript
interface PlanetaryPosition {
  id: string;
  planet: string; // Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
  sign: string;
  degree: number;
  house?: number;
  isRetrograde: boolean;
  aspects: Aspect[];
}
```

### HouseCusp

```typescript
interface HouseCusp {
  id: string;
  houseNumber: number; // 1-12
  sign: string;
  degree: number;
}
```

### Aspect

```typescript
interface Aspect {
  id: string;
  targetPlanet: string;
  aspectType: AspectType;
  orb: number;
  isExact: boolean;
}
```

### Aspect Types

- `CONJUNCTION` - 0° (orb: 8°)
- `SEXTILE` - 60° (orb: 6°)
- `SQUARE` - 90° (orb: 8°)
- `TRINE` - 120° (orb: 8°)
- `OPPOSITION` - 180° (orb: 8°)
- `QUINCUNX` - 150° (orb: 3°)
- `SEMISEXTILE` - 30° (orb: 3°)
- `SEMISQUARE` - 45° (orb: 3°)

### Chart Types

- `NATAL` - Birth chart
- `SOLAR_RETURN` - Solar return chart
- `LUNAR_RETURN` - Lunar return chart
- `TRANSIT` - Transit chart
- `PROGRESSED` - Progressed chart
- `COMPOSITE` - Composite chart
- `SYNASTRY` - Synastry chart

## 📝 Request Examples

### Create Astrology Chart

```bash
POST /v1/astrology-charts
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthLocation": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "timezone": "America/New_York",
  "chartType": "NATAL"
}
```

**Response Example:**

```json
{
  "success": true,
  "message": "Astrology chart created successfully",
  "data": {
    "id": "chart_123",
    "userId": "user_456",
    "birthDate": "1990-05-15T00:00:00.000Z",
    "birthTime": "14:30",
    "birthLocation": "New York, NY",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York",
    "sunSign": "Taurus",
    "moonSign": "Pisces",
    "risingSign": "Scorpio",
    "chartType": "NATAL",
    "isApproved": true,
    "chartInterpretation": "Your Taurus Sun sign indicates your core personality...",
    "astrologerNotes": "Chart calculated using enhanced astrological algorithms...",
    "planetaryPositions": [
      {
        "id": "pos_1",
        "planet": "Sun",
        "sign": "Taurus",
        "degree": 125.7,
        "house": 5,
        "isRetrograde": false,
        "aspects": [
          {
            "id": "aspect_1",
            "targetPlanet": "Moon",
            "aspectType": "TRINE",
            "orb": 2.3,
            "isExact": false
          }
        ]
      }
    ],
    "houseCusps": [
      {
        "id": "cusp_1",
        "houseNumber": 1,
        "sign": "Scorpio",
        "degree": 240.5
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### Update Astrology Chart

```bash
PUT /v1/astrology-charts/:chartId
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "birthTime": "15:00",
  "chartInterpretation": "Updated interpretation"
}
```

### Get User Charts with Filters

```bash
GET /v1/astrology-charts/user?chartType=NATAL&limit=10&offset=0
Authorization: Bearer <jwt_token>
```

### Search Charts by Sun Sign

```bash
GET /v1/astrology-charts/search/sign/Leo?limit=20
```

### Get Detailed Chart with Planetary Positions

```bash
GET /v1/astrology-charts/:chartId/detailed
Authorization: Bearer <jwt_token>
```

**Response Example:**

```json
{
  "success": true,
  "message": "Detailed astrology chart retrieved successfully",
  "data": {
    "id": "chart_123",
    "sunSign": "Taurus",
    "moonSign": "Pisces",
    "risingSign": "Scorpio",
    "planetaryPositions": [
      {
        "planet": "Sun",
        "sign": "Taurus",
        "degree": 125.7,
        "house": 5,
        "isRetrograde": false,
        "aspects": [
          {
            "targetPlanet": "Moon",
            "aspectType": "TRINE",
            "orb": 2.3,
            "isExact": false
          }
        ]
      }
    ],
    "houseCusps": [
      {
        "houseNumber": 1,
        "sign": "Scorpio",
        "degree": 240.5
      }
    ]
  }
}
```

### Get Planetary Positions Only

```bash
GET /v1/astrology-charts/:chartId/planetary-positions
Authorization: Bearer <jwt_token>
```

### Get Chart Aspects Only

```bash
GET /v1/astrology-charts/:chartId/aspects
Authorization: Bearer <jwt_token>
```

## 🔍 Query Parameters

### Filtering

- `userId` - Filter by user ID (admin only)
- `chartType` - Filter by chart type

- `isApproved` - Filter by approval status
- `sunSign` - Filter by sun sign
- `moonSign` - Filter by moon sign
- `risingSign` - Filter by rising sign

### Date Range

- `startDate` - Start date for filtering (ISO format)
- `endDate` - End date for filtering (ISO format)

### Pagination

- `limit` - Number of results per page (1-100, default: 20)
- `offset` - Number of results to skip (default: 0)

## ✅ Validation

The API includes comprehensive input validation using Joi schemas and custom middleware:

### Input Validation Middleware

- **`validateCreateChartRequest`**: Validates chart creation requests
- **`validateUpdateChartRequest`**: Validates chart update requests
- **`validateChartId`**: Validates chart ID format and existence
- **`validateSunSign`**: Validates astrological sun sign values
- **`validatePagination`**: Validates pagination parameters
- **`validateDateRange`**: Validates date range filters
- **`sanitizeChartData`**: Sanitizes input data to prevent XSS

### Validation Rules

**Birth Data:**

- **Birth Date**: Must be valid date between 1900 and next year
- **Birth Time**: Must be in HH:MM format (24-hour) or null
- **Birth Location**: Required string, max 255 characters
- **Coordinates**: Latitude (-90 to 90), Longitude (-180 to 180)
- **Timezone**: Valid IANA timezone identifier

**Chart Data:**

- **Chart Type**: Must be valid enum value (NATAL, SOLAR_RETURN, etc.)
- **String Lengths**: Enforced maximum lengths for all text fields
- **Boolean Flags**: Must be true/false values
- **Numeric Values**: Proper number validation with range checks

**Query Parameters:**

- **Pagination**: Limit (1-100), Offset (≥0)
- **Date Ranges**: Valid ISO date format
- **Filters**: Valid enum values for signs and chart types

### Error Handling

Validation errors return detailed messages with field-specific information:

```json
{
  "success": false,
  "message": "Validation failed",
  "error": "Invalid input data",
  "details": [
    {
      "field": "birthDate",
      "message": "Birth date must be a valid date"
    }
  ]
}
```

## 🚦 Rate Limiting

- **Window**: 15 minutes
- **Limit**: 100 requests per IP address
- **Headers**: Standard rate limit headers included

## 📈 Response Format

All API responses follow a consistent format:

```typescript
{
  success: boolean;
  message: string;
  data?: any;
  count?: number;
  pagination?: {
    limit: number;
    offset: number;
    hasMore: boolean;
  };
  error?: string;
}
```

## 🛡️ Security Features

- **Input Sanitization**: XSS protection and data cleaning
- **Authentication**: JWT-based secure authentication
- **Authorization**: Role-based access control
- **Rate Limiting**: Protection against abuse
- **Validation**: Comprehensive input validation
- **Error Handling**: Secure error messages

## 🚀 Redis Integration

The API includes comprehensive Redis integration for enhanced performance and scalability:

### Caching Strategy

- **Chart Data Caching**: Frequently accessed chart data is cached for improved response times
- **Planetary Position Caching**: Complex astrological calculations are cached to reduce computational overhead
- **User Session Caching**: User authentication sessions are stored in Redis for fast access
- **Rate Limiting Storage**: Rate limiting data is stored in Redis for distributed rate limiting

### Redis Configuration

```typescript
// Redis client configuration
const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD,
  db: parseInt(process.env.REDIS_DB || '0'),
  retryDelayOnFailover: 100,
  maxRetriesPerRequest: 3,
});
```

### Cache Keys

- `chart:{chartId}` - Complete chart data
- `positions:{chartId}` - Planetary positions for a chart
- `aspects:{chartId}` - Chart aspects data
- `user:{userId}:charts` - User's chart list
- `stats:charts` - Chart statistics

### Cache TTL (Time To Live)

- **Chart Data**: 1 hour (3600 seconds)
- **Planetary Positions**: 30 minutes (1800 seconds)
- **User Sessions**: 24 hours (86400 seconds)
- **Statistics**: 15 minutes (900 seconds)

### Redis Scripts

The project includes utility scripts for Redis management:

```bash
# Setup Redis environment
npm run setup:redis

# Test Redis connection
npm run test:redis
```

## 🔧 Setup & Installation

### Prerequisites

- Node.js 18+
- PostgreSQL database
- Redis (for caching and session management)
- TypeScript 5.9+

### Key Dependencies

The API is built with modern, production-ready technologies:

**Core Framework:**

- `express` - Web framework for Node.js
- `typescript` - Type-safe JavaScript development
- `tsx` - TypeScript execution and development server

**Database & ORM:**

- `` - Type-safe database client
- `prisma` - Database toolkit and ORM

**Authentication & Security:**

- `jsonwebtoken` - JWT token handling
- `bcryptjs` - Password hashing
- `express-rate-limit` - Rate limiting protection

**Astrology & Calculations:**

- `@astrodraw/astrochart` - Professional astrology chart generation
- `astrology-js` - Astrological calculations and algorithms

**Caching & Performance:**

- `ioredis` - Redis client for caching
- `redis` - Redis database driver

**Validation & Utilities:**

- `joi` - Schema validation
- `winston` - Logging framework
- `cors` - Cross-origin resource sharing

### Installation

1. **Clone the repository**

   ```bash
   git clone <repository-url>
   cd schematics-backend
   ```

2. **Install dependencies**

   ```bash
   # Using npm
   npm install

   # Or using pnpm (recommended)
   pnpm install
   ```

3. **Environment Configuration**

   ```bash
   cp .env.example .env
   # Configure your environment variables
   ```

4. **Database Setup**

   ```bash
   npx prisma generate
   npx prisma migrate dev
   ```

5. **Start the server**

   ```bash
   # Development mode with hot reload
   npm run dev

   # Or using pnpm
   pnpm dev

   # Production build
   npm run build
   npm start
   ```

## 🧪 Testing

```bash
# Run all tests
npm test

# Run astrology chart tests specifically
npm test -- --grep "astrology"

# Run with coverage
npm run test:coverage
```

## 📚 API Documentation

The API includes comprehensive documentation:

- **Swagger/OpenAPI**: Available at `/api-docs`
- **Health Check**: `/v1/astrology-charts/health`
- **Error Handling**: Detailed error messages with error codes
- **Rate Limiting**: Headers show current usage
- **Endpoint Discovery**: 404 responses include available endpoints and authentication requirements
- **Response Examples**: Detailed response examples for all endpoints
- **Data Models**: Complete TypeScript interfaces for all data structures

## 🔄 Database Schema

The astrology charts are stored using Prisma ORM with the following models and relationships:

### Core Models

**AstrologyChart Model:**

```prisma
model AstrologyChart {
  id     String @id @default(cuid())
  userId String
  user   users  @relation(fields: [userId], references: [id], onDelete: Cascade)

  // Birth data
  birthDate     DateTime
  birthTime     String? // Format: "HH:MM"
  birthLocation String
  latitude      Float?
  longitude     Float?
  timezone      String?

  // Astrological calculations
  sunSign    String
  moonSign   String?
  risingSign String?

  // Chart metadata
  chartType  ChartType @default(NATAL)
  isApproved Boolean   @default(true)

  // Relationships
  planetaryPositions PlanetaryPosition[]
  houseCusps         HouseCusp[]

  // Timestamps
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("astrology_charts")
}
```

**PlanetaryPosition Model:**

```prisma
model PlanetaryPosition {
  id      String         @id @default(cuid())
  chartId String
  chart   AstrologyChart @relation(fields: [chartId], references: [id], onDelete: Cascade)

  planet       String // Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
  sign         String
  degree       Float
  house        Int?
  isRetrograde Boolean  @default(false)
  aspects      Aspect[]

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("planetary_positions")
}
```

**HouseCusp Model:**

```prisma
model HouseCusp {
  id      String         @id @default(cuid())
  chartId String
  chart   AstrologyChart @relation(fields: [chartId], references: [id], onDelete: Cascade)

  houseNumber Int
  sign        String
  degree      Float

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("house_cusps")
}
```

**Aspect Model:**

```prisma
model Aspect {
  id       String            @id @default(cuid())
  planetId String
  planet   PlanetaryPosition @relation(fields: [planetId], references: [id], onDelete: Cascade)

  targetPlanet String
  aspectType   AspectType
  orb          Float
  isExact      Boolean @default(false)

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("aspects")
}
```

### Enums

```prisma
enum ChartType {
  NATAL
  SOLAR_RETURN
  LUNAR_RETURN
  TRANSIT
  PROGRESSED
  COMPOSITE
  SYNASTRY
}

enum AspectType {
  CONJUNCTION
  SEXTILE
  SQUARE
  TRINE
  OPPOSITION
  QUINCUNX
  SEMISEXTILE
  SEMISQUARE
}
```

### Enhanced Features

- **Automatic Population**: Planetary positions and aspects are automatically calculated and stored
- **Relationship Integrity**: Proper foreign key relationships ensure data consistency
- **Cascade Operations**: Deleting a chart removes all related planetary positions and aspects
- **Indexed Queries**: Optimized database indexes for fast chart retrieval
- **Data Validation**: Database-level constraints ensure data integrity
- **Type Safety**: Full TypeScript support with Prisma client generation

## 🌟 Astrological Calculations

The API now includes comprehensive astrological calculations:

### Planetary Positions

- **Sun, Moon, Mercury, Venus, Mars**: Personal planets with accurate positioning
- **Jupiter, Saturn**: Social planets with orbital calculations
- **Uranus, Neptune, Pluto**: Outer planets with generational influences
- **Retrograde Detection**: Automatic identification of retrograde motion
- **Degree Precision**: Accurate degree calculations for all planetary positions

### House System

- **12-House System**: Complete astrological house calculations
- **House Cusps**: Precise cusp positions for all 12 houses
- **House Rulership**: Automatic determination of house rulers
- **Equal House System**: Currently implemented with plans for Placidus and Koch systems

### Aspects

- **Major Aspects**: Conjunction, Sextile, Square, Trine, Opposition
- **Minor Aspects**: Quincunx, Semisextile, Semisquare
- **Orb Calculations**: Precise orb measurements for aspect accuracy
- **Exact Aspects**: Identification of exact orbs within 1 degree

### Sign Calculations

- **Sun Sign**: Accurate tropical zodiac calculations
- **Moon Sign**: Lunar position calculations based on birth data
- **Rising Sign**: Ascendant calculations using birth time and location
- **Sign Rulership**: Automatic determination of planetary rulerships

### Calculation Accuracy

- **Tropical Zodiac**: Uses the standard Western tropical zodiac system
- **Geographic Coordinates**: Requires latitude and longitude for accurate calculations
- **Time Precision**: Birth time is essential for rising sign and house calculations
- **Orb Tolerance**: Configurable orb tolerances for aspect calculations
- **Fallback System**: Graceful degradation when advanced calculations fail

### Technical Implementation

- **Algorithm-Based**: Uses mathematical algorithms for planetary position calculations
- **Database Integration**: Automatic storage of calculated positions and aspects
- **Performance Optimized**: Efficient calculations with minimal computational overhead
- **Error Handling**: Comprehensive error handling with meaningful error messages
- **Logging**: Detailed logging for debugging and monitoring calculation accuracy

## 📊 Current Implementation Status

### ✅ Implemented Features

- **Core CRUD Operations**: Complete create, read, update, delete functionality
- **Authentication & Authorization**: JWT-based auth with role-based access control
- **Input Validation**: Comprehensive validation using Joi schemas
- **Rate Limiting**: Express rate limiting with Redis storage
- **Redis Caching**: High-performance caching for chart data
- **Database Integration**: Full Prisma ORM integration with PostgreSQL
- **Error Handling**: Comprehensive error handling and logging
- **API Documentation**: Complete endpoint documentation with examples
- **Health Checks**: Service health monitoring endpoints
- **Admin Controls**: Chart verification and approval system

### 🚧 In Development

- **Astrological Calculations**: Advanced planetary position calculations
- **Chart Interpretations**: AI-powered chart analysis
- **Performance Optimization**: Query optimization and caching strategies

### 📋 Planned Features

- **Chart Visualization**: SVG/PNG chart generation
- **Advanced House Systems**: Multiple house system support
- **Transit Calculations**: Real-time planetary transit analysis
- **Export Functionality**: PDF and image export capabilities

## 🚀 Future Enhancements

- **Swiss Ephemeris Integration**: Professional-grade ephemeris calculations
- **Chart Visualization**: SVG/PNG chart generation with customizable themes
- **Predictive Astrology**: Transit and progression calculations
- **Advanced House Systems**: Placidus, Koch, and other house systems
- **Asteroid Calculations**: Chiron, Ceres, and other important asteroids
- **Community Features**: Chart sharing and social interactions
- **Mobile App**: React Native mobile application
- **AI Integration**: Enhanced AI-powered chart interpretations
- **Real-time Transits**: Current planetary transits and their effects
- **Compatibility Analysis**: Synastry and composite chart calculations
- **Chart Visualization**: Interactive chart rendering with customizable themes
- **Export Features**: PDF and image export capabilities
- **Mobile Optimization**: Enhanced mobile API responses

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License.

## 🆘 Support

For support and questions:

- **Documentation**: Check this README and API docs
- **Issues**: Create an issue on GitHub
- **Email**: Contact the development team

## 🔗 Related Links

- [Prisma Documentation](https://www.prisma.io/docs/)
- [Express.js Documentation](https://expressjs.com/)
- [TypeScript Documentation](https://www.typescriptlang.org/)
- [Astrology Resources](https://www.astro.com/)

---

**Built with ❤️ by the Schematics Backend Team**