# CLAUDE.md

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

## Project Overview

BaniBanna — Muslim matrimonial matching platform. Laravel 11 monolith with swipe-based discovery, real-time encrypted chat, and an admin panel.

## Commands

### Development (all three in parallel)
```bash
php artisan serve          # Laravel dev server
php artisan queue:listen   # Process queued jobs
npm run dev                # Vite HMR
```
Or use the combined command:
```bash
npm run dev  # runs concurrently: php artisan serve + queue:listen + vite
```

### Build & Assets
```bash
npm run build              # Production Vite build
php artisan optimize       # Cache config/routes/views
```

### Testing
```bash
php artisan test                          # All tests
php artisan test tests/Feature/Foo.php   # Single test file
php artisan test --filter=test_name       # Single test by name
vendor/bin/phpunit                        # Direct PHPUnit
```
Tests use MySQL (not SQLite) — requires running DB connection matching `.env`.

### Code Style
```bash
vendor/bin/pint            # Laravel Pint formatter
vendor/bin/pint --test     # Check without fixing
```

### Database
```bash
php artisan migrate
php artisan migrate:fresh --seed          # Wipe + reseed
```

### WebSockets (Reverb)
```bash
php artisan reverb:start   # Start Reverb WebSocket server
```

## Architecture

### Request Flow
Routes split across: `routes/web.php` (public), `routes/user_routes.php` (authenticated users), `routes/admin_auth.php` (admin), `routes/api.php` (Sanctum-authenticated API).

**Middleware stack of note:**
- `CheckProfileCompletion` — redirects users without complete profiles
- `CheckIfBlocked` — enforces mutual blocks before serving user pages
- `UpdateLastActive` — updates `last_active_at` on every request
- `SetSessionCookie` — custom session cookie handling

### Frontend Stack
Blade templates + **Livewire 3** for reactive components + **Alpine.js** for lightweight DOM interactivity. Not a SPA. Real-time features (chat, notifications) use **Laravel Echo** + **Reverb** (self-hosted WebSocket server, replaces Pusher).

Livewire components: `MessengerComponent`, `SwipeableCards`, `AccountUpdateSettings`, `UserPhotosComponent`.

### Data Model
53 models. Core domain: `User` → `Profile` → `PartnerExpectations` for matching. Chat: `ChatThread` → `ChatMessages` (encrypted via `HasEncryptedChat` trait). Matching events: `SwipeRightEvent` → `SwipeRightListener`.

Key traits (in `app/Traits/`):
- `HasMedia` — profile photo upload/manipulation via Intervention Image 3
- `HasEncryptedChat` — encrypts/decrypts chat message content
- `HasNotifications` — notification fan-out
- `HasButtons` — renders dynamic action buttons on profiles

### Admin Panel
`app/Http/Controllers/Admin/` — 18+ controllers. Uses **AdminLTE 3** template (`jeroennoten/laravel-adminlte`) with **Yajra DataTables** for server-side tables.

### Services & Integrations
- `app/Services/NotificationService.php` — centralized notification dispatch
- `app/Services/PackageService.php` — subscription/membership logic
- `app/Services/Outlook/` + `OutlookMailServiceProvider` — Microsoft OAuth2 for admin transactional email. Token managed by `TokenRepository`. Registered as custom mail transport.

### Jobs
- `BlurUserPhotos` — queued job to apply blur to profile photos
- `MatchProfilesJob` — background matching computation

### Enums
`app/Enums/`: `ProfileFor`, `HabitOption`, `ChildrenEnum` — used on profile forms and query scopes.

### helpers.php
`app/helpers.php` (10KB) — auto-loaded globally. Check here before writing utility functions.

## Key Packages
| Package | Purpose |
|---|---|
| `livewire/livewire 3.5` | Reactive Blade components |
| `laravel/reverb 1.0` | Self-hosted WebSocket server |
| `intervention/image 3.11` | Image resize/blur for profile photos |
| `jeroennoten/laravel-adminlte 3.14` | Admin panel template |
| `yajra/laravel-datatables 11.0` | Server-side DataTables |
| `laravel/sanctum 4.0` | API token auth |
| `stevenmaguire/oauth2-microsoft` | Outlook OAuth2 for mail |
| `laravel/reverb` | WebSockets (not Pusher) |