# REGITICKET: Professional Migration & Scalability Master Plan

## 1. Project Vision
**Regiticket** is evolving from a WordPress-based sports event plugin into a high-performance, multi-niche **SaaS Event Management Platform**. This Laravel 11 implementation replaces all legacy dependencies (WooCommerce, The Events Calendar) with a custom, scalable architecture designed for sports, concerts, theater, and corporate events.

---

## 2. Infrastructure: Docker Environment (Laravel Sail)
The project must be containerized to ensure consistency across environments. 

### 2.1 Docker Services
*   **App (PHP 8.3):** Laravel 11.
*   **MySQL 8.0:** Core database.
*   **Mailpit:** Local mail server for testing notifications and ticket delivery.
*   **Redis:** For caching, session management, and high-performance event queues.
*   **Selenium/Chrome:** For automated browser testing of the checkout flow.

### 2.2 Environment Variables (`.env`)
The agent should configure:
*   `DB_CONNECTION=mysql`
*   `MAIL_MAILER=smtp` (Host: `mailpit`, Port: `1025`)
*   `STRIPE_KEY`, `STRIPE_SECRET`, `STRIPE_WEBHOOK_SECRET`
*   `PAYPAL_CLIENT_ID`, `PAYPAL_SECRET`

---

## 3. Database Architecture (Scalable Schema)

### 3.1 Entities & Migrations
The database is designed for multi-niche support using relational integrity and JSON columns for flexibility.

#### `events`
*   `id`, `uuid`, `organizer_id` (FK), `venue_id` (FK), `category_id` (FK).
*   `title`, `slug`, `description`, `short_description`.
*   `start_date`, `end_date`, `timezone`.
*   `status` (`draft`, `pending`, `published`, `cancelled`).
*   `metadata` (JSON): niche-specific data (e.g., race distance for sports, artist for concerts).

#### `ticket_types` (Unified Inventory)
*   `id`, `event_id` (FK), `name`, `price` (Decimal 10,2), `capacity` (Integer), `quantity_sold`.
*   `is_active`, `sale_start`, `sale_end`.

#### `orders` & `transactions`
*   `orders`: `user_id`, `total_amount`, `platform_fee`, `net_organizer_amount`, `status` (`pending`, `completed`, `refunded`).
*   `transactions`: `order_id`, `gateway` (`stripe`, `paypal`), `reference_id`, `payload` (JSON).

#### `attendees` (Individual Tickets)
*   `id`, `order_id` (FK), `ticket_type_id` (FK), `security_code` (UUID/Hash).
*   `holder_name`, `holder_email`, `registration_data` (JSON: T-shirt size, Seat number, etc.).
*   `checked_in_at` (Timestamp), `checkin_by` (User FK).

---

## 4. Payment Engineering: Split Payments
The platform implements a native commission model:
**Formula:** `Fee = ($2.99 * Qty) + (GrossTotal * 0.05)`

### 4.1 Stripe Connect
*   **Standard/Express Accounts:** Organizers must link their Stripe account.
*   **Transfer Logic:** On successful payment, the platform takes the `Fee` and triggers a transfer/payout to the Organizer's `stripe_account_id`.

---

## 5. Security & Compliance (OWASP Standards)

### 5.1 Access Control (A01:2021)
*   **Policies:** Every resource (Event, Order, Attendee) must have a Laravel Policy. 
*   **Rule:** `Organizer can only see events they created. Admin can see everything.`

### 5.2 Cryptographic Failures (A02:2021)
*   **Data Encryption:** Sensitive organizer bank info and PII must be encrypted using Laravel's `Encryption` facade.

### 5.3 Injection Prevention (A03:2021)
*   Strict use of Eloquent and Query Builder. No raw SQL.
*   Input validation using `FormRequests`.

### 5.4 Check-in Integrity
*   The QR `security_code` must be a high-entropy string (UUID v4) to prevent guessing.
*   **Rate Limiting:** Protect the scan endpoint from brute-force attempts.

---

## 6. Development Workflow for Cursor Agent

### Phase 1: Environment Setup
1. Initialize Laravel 11.
2. Configure `docker-compose.yml` with MySQL and Mailpit.
3. Install **FilamentPHP v3**.

### Phase 2: Core Domain
1. Create Migrations and Models with strict type hinting.
2. Implement **Filament Resources** for:
    *   **Admin:** Global management, Organizer approval, Category management.
    *   **Organizer:** Unified Event Creator (Wizard with Ticket Repeater).

### Phase 3: Frontend & Sales
1. Implement Landing Page with search/filters (Inertia + Vue).
2. Create the Checkout flow:
    *   Select Tickets -> Fill Attendee Info -> Pay via Stripe.
3. Handle Webhooks to fulfill orders and generate PDFs.

### Phase 4: QR Check-in System
1. Build a specialized view for the Scanner (PWA ready).
2. Logic: Validate `security_code` against `attendee_id` and `event_id`.
3. Action: Update `checked_in_at` and log entry.

---

## 7. Scalability Strategy
*   **Modular Architecture:** Keep niche-specific logic in Service classes.
*   **Event Sourcing (Future):** Prepare for high-volume ticket sales using Redis for locking stock during the checkout process (preventing overselling).
*   **Localization:** Support for multi-language and multi-currency from the start.
