# Numerology Platform API Architecture

## Purpose

The API provides a secure backend for the web and mobile
applications.

The API is responsible for:

- User authentication
- User profiles
- Birth data
- Name data
- Numerology calculations
- Power Cycle calculations
- Future numerology features
- API validation
- Consistent JSON responses

## Architecture

Client Applications:

- Web Application
- Mobile Application

Both communicate with:

PHP REST API

The API communicates with:

- Numerology Engine
- MySQL Database

## Principle

Numerology methodology must remain in the PHP backend.

Web and mobile clients must not duplicate calculation logic.

## Authentication

Users will eventually be able to:

- Register
- Log in
- Log out
- Maintain their profile
- Store their birth information
- Store their name information
- Request numerology calculations

## Planned API Areas

### Authentication

POST /api/auth/register

POST /api/auth/login

POST /api/auth/logout

### User

GET /api/user/profile

PUT /api/user/profile

### Numerology

POST /api/numerology/profile

POST /api/numerology/personal-year

POST /api/numerology/personal-month

POST /api/numerology/personal-day

POST /api/numerology/power-cycle

## Response Format

Successful responses should use JSON.

Example:

{
    "success": true,
    "data": {}
}

Errors should use:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable message"
    }
}

## Security Principles

- Validate every request.
- Never trust client-supplied calculated values.
- Use prepared SQL statements.
- Never expose database credentials.
- Never expose PHP warnings or stack traces in production.
- Authentication must be handled server-side.
- Passwords must never be stored as plain text.
- API responses should contain only necessary data.

## Development Principle

The API should call the existing tested Numerology
calculators rather than duplicating their logic.

## Current Verified Components

NumerologyProfileCalculator:
11/11 tests passing.

PowerCycleCalculator:
7/7 tests passing.

Power Cycle Integration:
5/5 tests passing.