# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Laravel 12** REST API backend for the **PMWani mobile app** (Flutter). It runs on XAMPP (local development) and serves a WiFi/internet plan management platform with a loyalty points system called "Petals". Payment integration uses Razorpay.

## Common Commands

```bash
# Install dependencies
composer install

# Full setup (install, .env, key, migrate, npm)
composer run setup

# Run dev server
php artisan serve

# Run migrations
php artisan migrate

# Run tests
composer test
# or: php artisan test

# Run a single test
php artisan test --filter TestClassName

# Code formatting (Laravel Pint)
./vendor/bin/pint

# Clear config cache
php artisan config:clear

# Tinker (REPL)
php artisan tinker
```

## Architecture

### API Structure

All routes are prefixed with `/api` (Laravel default). The API has two tiers:
- **Public routes** — login, signup, OTP verify, forgot password
- **Protected routes** — guarded by `auth:sanctum` middleware (Bearer token)

Authentication uses **Laravel Sanctum** tokens (created on login/OTP verify, deleted on logout).

### Key Domain Concepts

- **Petals** — loyalty points system. Users earn petals by purchasing internet plans, from ads, or by buying petal packs. Petals can be used as discounts (1 petal = Re 1 off) on plan purchases or gifted to others.
- **Internet Plans** — WiFi plans with a price, validity (days), and petals reward on purchase.
- **WiFi Routers** — physical routers users can connect to; `RouterController` supports listing all or nearby (by location).
- **WiFi Sessions** — records of user internet sessions.
- **Orders** — created when a payment is initiated; `status=0` is pending, `status=1` is paid.
- **Challenges** — gamification feature with rewards.
- **Banners** — promotional banners for the app home screen.

### Controllers (`app/Http/Controllers/Api/`)

| Controller | Responsibility |
|---|---|
| `AuthController` | Login, signup, OTP verify, forgot/change password, logout |
| `ProfileController` | Show, update, complete profile, upload image |
| `HomeController` | Account details dashboard |
| `PetalsController` | Petal balance, plans, earn/gift/add petals, transaction history |
| `PaymentController` | Order summary, Razorpay initiate/verify, payment history |
| `InternetPlanController` | List available internet plans |
| `RouterController` | List all routers or nearby routers |
| `WifiSessionController` | List user wifi sessions |
| `NotificationController` | List notifications, mark all read |
| `BannerController` | List promotional banners |
| `ChallengeController` | List challenges |
| `MediaController` | File/image upload |

### Models and Relationships

- `User` — has one `UserPetal`, has many `Order`, `Notification`, `WifiSession`, `PetalTransaction`
- `UserPetal` — tracks `available_petals` and `used_petals` per user
- `PetalTransaction` — log of petal earn/use events (`transaction_type`: `earned` | `used`)
- `Order` — belongs to `User` and `InternetPlan`; tracks Razorpay order/payment IDs
- `WifiRouter` — physical router with location data
- `WifiSession` — session record linking user to router

`User::toAppArray()` is the canonical method for serializing user data to the Flutter app format.

### Payment Flow

1. Client calls `POST /api/userpetals/payment/initiate` → creates an `Order` with `status=0`, returns a Razorpay order ID
2. Flutter app handles Razorpay checkout
3. Client calls `POST /api/userpetals/payment/verify` → marks order `status=1`, deducts petals if used, awards petals from plan
4. For purchasing petal packs directly: use `POST /api/userpetals/payment/verify/petals`

**Note:** Razorpay SDK calls are currently commented out in `PaymentController` with mock order IDs. To enable real payments, uncomment the Razorpay SDK blocks and set `RAZORPAY_KEY_ID` / `RAZORPAY_KEY_SECRET` in `.env`.

### Development Notes

- OTP echo in signup/resend responses is gated behind `DEV_OTP_IN_RESPONSE=true` (default `false`). Never set this in production — let SMS delivery handle it.
- `AUTO_VERIFY_OTP=true` bypasses OTP entirely (dev convenience). Never set in production.
- SMS delivery is implemented via `SmsService` (MSG91 driver in production, `log` driver in development). Configure `SMS_DRIVER` and MSG91 credentials in `.env`.
- Profile completeness is determined by `otp_verified_on !== null` on the User.
- The `.env` file must be configured with DB credentials for XAMPP (typically MySQL on port 3306).