# VPandit API (Laravel 11)

REST API for the React SPA — a **parallel-run** migration of the live PHP app. It
reuses the **existing VPandit MySQL database as-is** and shares PII encryption with
the PHP `crypto.php`, so both stacks run against the same data during cutover.

## Setup (on your XAMPP box or any PHP 8.2+ host)

```bash
cd vpandit-api
composer install
cp .env.example .env
php artisan key:generate            # sets APP_KEY (Laravel's own key, NOT the PII key)
# Edit .env:
#   DB_*        -> your existing VPandit database
#   VP_APP_KEY  -> paste the base64 string from C:\xampp\htdocs\VPandit\config\app_key.php
php artisan serve                   # http://localhost:8000
```

> **PII parity is critical.** `VP_APP_KEY` must equal the value returned by the PHP
> app's `config/app_key.php`. If it differs, PII columns written by one stack cannot
> be read by the other. Never commit this value; back it up (loss = unrecoverable PII).

## Verify PII round-trip matches PHP

```bash
php artisan vpandit:pii-check 9876543210
# enc: ENC::...   dec: 9876543210   roundtrip: OK
```

## Endpoints (this phase)

| Method | Path | Auth | Notes |
|--------|------|------|-------|
| GET  | `/api/ping` | public | health |
| POST | `/api/auth/login` | public | `{email,password}` → Sanctum token |
| GET  | `/api/auth/me` | bearer | current user |
| POST | `/api/auth/logout` | bearer | revoke token |
| POST | `/api/numerology/compute` | public | `{dob:YYYY-MM-DD, gender, name, ...}` → full profile |
| GET  | `/api/numerology/customers` | bearer | saved vault (PII decrypted) |
| GET  | `/api/numerology/customers/{id}` | bearer | customer + computed profile |

## Tests

```bash
php artisan test                    # or: ./vendor/bin/phpunit
```

`tests/Unit/NumerologyTest.php` asserts numerology parity with the PHP engine
(Kua for 18-03-1971 male = 2; Lo Shu grid filled with the Kua) with no DB needed.

## Architecture

Controllers (HTTP + FormRequest validation) → Services (business logic; numerology
delegates to the exact PHP functions ported verbatim in `app/Support/numerology_lib.php`)
→ Eloquent models mapped onto existing tables. See the migration blueprint in the
project docs for the full module sequence.
