# Basketloot System Overview

## Product surface

Basketloot is a Laravel 8 rewards platform. Guests can browse the marketing site
and public offers. Members earn points through provider offerwalls, direct
campaigns, referrals, and bonuses, then request cashouts. Staff operate the
platform through a role-aware administration area.

## Request flow

1. `routes/web.php` serves public pages, authentication, and the member portal.
2. `routes/admin.php` serves analytics, users, leads, campaigns, payments,
   withdrawals, support, settings, callback logs, and moderation tools.
3. `routes/api.php` receives third-party provider postbacks.
4. Provider controllers verify the configured signature and transaction ID.
5. `Controller::creditLead()` credits points and creates the lead in one database
   transaction. The `(company, trx)` unique index prevents duplicate credits.
6. Middleware logs a redacted callback payload; secrets and signatures are not
   persisted in callback logs.

## Core domains

- **Identity and access:** Laravel authentication, email verification, optional
  two-factor authentication, IP checks, and role/permission-aware admin access.
- **Earning:** offerwalls, imported provider offers, direct campaigns, click
  attribution, leads, rules, held/rejected reviews, and live activity.
- **Rewards:** point balances, bonus codes, referral commissions, leaderboard
  awards, payment methods, withdrawals, and face verification for cashouts.
- **Operations:** analytics, site settings, callback logs, support tickets,
  notifications, exports, recycle-bin behavior, and database backups.
- **Presentation:** Blade layouts and Livewire admin/member tables backed by the
  shared design tokens in `design-system/MASTER.md` and `public/assets/css/style.css`.

## Data integrity and security boundaries

- Provider callbacks fail closed when a signature scheme is missing or unknown.
- Lead creation, balance crediting, and referral commission updates share one
  transaction; duplicate postbacks roll the whole transaction back.
- Cashout creation locks the user row and decrements the balance atomically.
- Profile uploads reject SVG, and face captures must decode as bounded PNG/JPEG
  images.
- Callback payloads recursively redact credentials before logging.
- Site colors accept complete six-digit hexadecimal values only.
- Global security headers are emitted by `SecurityHeaders` middleware.

## Scheduled operations

The scheduler in `app/Console/Kernel.php` resets daily/monthly points, syncs
provider offers every five minutes, curates offers daily, auto-approves eligible
held leads every thirty minutes, and creates a daily database backup. Production
must run Laravel's scheduler every minute and a queue worker if queued jobs or
notifications are enabled.

## Development and verification

```bash
php artisan migrate
php artisan test
npm run production
php artisan optimize:clear
php artisan serve --host=127.0.0.1 --port=8010
```

The application uses the configured database for normal runtime. Tests use the
isolated test environment from `phpunit.xml`; never point it at production data.

## Deployment essentials

- Serve only the `public/` directory and keep `.env` inaccessible.
- Set `APP_ENV=production`, `APP_DEBUG=false`, and the canonical HTTPS `APP_URL`.
- Configure provider secrets independently in the production environment.
- Run migrations before enabling callbacks, then warm configuration and views.
- Configure the scheduler, backups, HTTPS, and log rotation.
- See `CPANEL_DEPLOYMENT.md` for the current cPanel-specific procedure.
