# Vaastu Wisdom

Vaastu Wisdom is a Laravel backend for the mobile application and its administrator panel.

## Current capabilities

- Customer registration with full name, phone number, email, and optional birth details.
- Customer authentication with email OTP.
- OTP verification, expiry, attempt limits, resend cooldown, and throttling.
- Queued email delivery for registration, login, and resend OTPs.
- Sanctum bearer tokens for mobile API authentication.
- Filament admin panel with email/password authentication.
- Filament database notification center for admin alerts.
- Collapsible desktop sidebar and full-width admin content layout.
- Admin customer listing, search, filtering, and read-only profile viewing.
- Versioned API foundation beginning with `/api/v1`.

## Requirements

- PHP 8.3+
- Composer 2+
- SQLite, MySQL, or PostgreSQL
- SMTP or another Laravel-supported mail transport for real OTP delivery

## Local setup

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
```

Configure Redis, the mail transport, and queue worker in `.env` before using real OTP delivery:

```env
REDIS_CLIENT=phpredis
QUEUE_CONNECTION=redis
CACHE_STORE=redis
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-mail-username
MAIL_PASSWORD=your-mail-password
MAIL_SCHEME=null
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Vaastu Wisdom"
```

The `log` mailer is suitable for local OTP inspection only. In production use a real mail transport, set `APP_DEBUG=false`, and provision the PHP Redis extension. Run a queue worker in the application environment so queued OTP emails are delivered:

```bash
php artisan queue:work redis --sleep=1 --tries=3 --timeout=90
php artisan schedule:work
```

Run the queue worker under Supervisor or systemd so it restarts after deploys and failures. Keep the worker timeout below Redis `retry_after` (the application default is 90 seconds versus a 120-second reservation window). For a production release, cache the verified configuration and routes:

```bash
php artisan optimize
php artisan migrate --force
php artisan queue:restart
```

The scheduler prunes OTP challenges hourly and expired Sanctum tokens daily. Configure `CORS_ALLOWED_ORIGINS` with the exact browser origins that may call the API; do not use `*` when credentials are enabled.

Never commit `.env` or provider credentials.

## Customer API

All API responses use this structure:

```json
{
  "success": true,
  "message": "Request completed successfully.",
  "data": {},
  "errors": []
}
```

Endpoints:

| Method | Endpoint | Purpose |
| --- | --- | --- |
| POST | `/api/v1/auth/register` | Create a customer account and send registration OTP |
| POST | `/api/v1/auth/register/resend-otp` | Recover a registration OTP by email when the challenge ID is lost |
| POST | `/api/v1/auth/register/verify-otp` | Verify registration OTP and receive a token |
| POST | `/api/v1/auth/login/request-otp` | Request a login OTP using the registered email |
| POST | `/api/v1/auth/login/verify-otp` | Verify login OTP and receive a token |
| GET | `/api/v1/me` | Fetch the authenticated customer profile |
| POST | `/api/v1/auth/logout` | Revoke the current customer token |

Send the registration phone number in E.164 format, for example `+919876543210`. Login requests use the registered email address and do not require the phone number. All API responses include an `X-Request-ID` header for safe request correlation.

Registration fields:

- `full_name` — required
- `phone_number` — required
- `birth_date` — optional
- `birth_time` — optional in `HH:MM` format
- `place_of_birth` — optional
- `email` — required; registration OTPs are sent here

OTP values are never returned by the API. The response contains a challenge ID, purpose, expiry time, and next resend time.

The client must store the latest `challenge_id` returned by registration or login for verification. Repeated login requests are blocked during the resend cooldown; request a new login OTP again after the cooldown. Registration OTP recovery uses `/api/v1/auth/register/resend-otp` with the customer email.

### Authentication examples

Registration collects both the phone number and email address:

```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "full_name": "Aarav Shah",
    "phone_number": "+919876543210",
    "email": "aarav@example.com"
  }'
```

Login uses the registered email address. The OTP is delivered to that email:

```bash
curl -X POST http://localhost:8000/api/v1/auth/login/request-otp \
  -H 'Content-Type: application/json' \
  -d '{"email":"aarav@example.com"}'
```

Use the returned `challenge_id` and the six-digit email OTP with the matching verify endpoint. Both existing verify endpoints accept an optional `device_name` field (maximum 80 characters):

```json
{
  "challenge_id": "01J...",
  "otp": "123456",
  "device_name": "Aarav's iPhone"
}
```

If `device_name` is omitted, the sanitized `User-Agent` is used. Successful verification returns a separate 30-day Sanctum bearer token for that device, including `device_name` and `expires_at`. Multiple devices remain signed in independently; logout revokes only the current token.

## OpenAPI documentation

Scramble generates the API documentation from the Laravel routes and request classes:

- UI: `/docs/api`
- OpenAPI JSON: `/docs/api.json`

Export the specification to a file when needed:

```bash
php artisan scramble:export --path=/tmp/vaastu-wisdom-api.json
```

## Admin panel

Open the Filament panel at:

```text
/admin
```

Admins use email/password authentication and are stored separately from customers. Public admin registration is disabled.

Create the first administrator interactively:

```bash
php artisan make:filament-user
```

The command uses the configured admin guard and creates an admin account for the Filament panel.

## Testing

Run the full test suite:

```bash
php artisan test
```

Run code formatting:

```bash
./vendor/bin/pint --dirty
```

Run `php artisan schedule:list` to verify the cleanup schedules and `php artisan scramble:export --path=/tmp/vaastu-wisdom-api.json` to verify the generated OpenAPI contract.

## Project status

The v1 authentication foundation is implemented. Future work can add customer profile updates, Vaastu content APIs, subscriptions, payments, notifications, and additional Filament resources without changing the existing authentication contract.
