# Venue Events Manager — Project Plan

## Product

**Venue Events Manager** is a Conference, Banquet and Events Management System for hotels, conference centres, banquet halls, gardens and event venues.

## Technology Stack

| Layer | Choice |
|-------|--------|
| Language | PHP 8.2+ |
| Framework | Laravel 12.x |
| Database | MySQL 8.0 / MariaDB (InnoDB, utf8mb4) |
| Templates | Blade (server-rendered) |
| UI | Radminly-inspired Tailwind CSS + Alpine.js |
| Calendar | FullCalendar (bundled assets) |
| PDF | barryvdh/laravel-dompdf (pure PHP) |
| Money | brick/math (decimal arithmetic) |
| Tests | PHPUnit |
| Deploy | cPanel shared hosting (no SSH required) |

## Core Domain Model

```
Customer
  └── Event Booking (authoritative operational record)
        ├── Space Reservations (booking_spaces)
        ├── Booking Items (products / packages)
        ├── Quotations (immutable snapshots when issued)
        ├── Invoices (immutable snapshots when issued)
        └── Payments
```

Quotations and invoices store billing/event/item snapshots. They never duplicate the booking record.

## Architecture Principles

1. Thin controllers; business logic in service classes.
2. Form Requests for validation; Policies for authorization.
3. Database transactions for financial ops and document conversion.
4. Row locking for double-booking prevention and document numbers.
5. Backed PHP enums for statuses and charge bases.
6. Single `AvailabilityService` and `PricingService` for all consumers.
7. Lazy expiry for provisional holds (no required cron).
8. Overdue invoice status calculated on read/update (no required cron).

## Service Layer

| Service | Responsibility |
|---------|----------------|
| AvailabilityService | Conflict detection, calendar states, hold expiry |
| PricingService | All line and document money calculations |
| DocumentNumberService | Concurrency-safe sequential numbers |
| BookingStatusService | Booking lifecycle transitions |
| PaymentStatusService | Invoice payment status from transactions |
| QuotationConversionService | Quote → invoice (no booking duplicate) |
| InvoiceService | Issue, void, overdue, snapshots |
| AuditService | Activity logging (no secrets) |
| AttachmentService | Secure private file storage |
| DashboardService | Dashboard aggregates |
| ReportService | Reports + CSV/PDF export |

## Implementation Phases

See `TASKS.md` for checkbox tracking.

1. Foundation (auth, RBAC, settings, audit, layout)
2. Customers & Spaces
3. Products, Packages, Pricing
4. Bookings, Holds, Availability
5. Quotations & Conversion
6. Invoices & Payments
7. Dashboard, Reports, Notifications
8. Attachments, Installer, cPanel package
9. Full tests, cleanup, final release

## Production Constraints

- Session: database or file
- Cache: file or database
- Queue: sync
- APP_ENV=production, APP_DEBUG=false
- No Docker, Redis, Supervisor, WebSockets, queue workers, or Node.js on production
- Optional cron documented; application must work without it

## Out of Scope (Phase Two)

Public booking portal, payment gateways, M-Pesa, WhatsApp/SMS, e-signatures, BEO workflow, inventory/procurement, staff scheduling, floor-plan editor, QR tickets, PMS/POS/accounting integrations, multi-property, native apps, AI.

## Default Property Settings

- Timezone: Africa/Nairobi
- Currency: KES
- Date format: d/m/Y
- Time format: 24-hour
