# System Architecture

## 1. High-Level Architecture Overview

The Calian Digital Hotel Platform follows a modern **Monolithic Single-Page Application (SPA)** architecture utilizing Laravel 11/12 as the backend core and Inertia.js with React 18 + TypeScript on the client side.

```text
+-------------------------------------------------------------------------------+
|                             CLIENT / USER LAYER                               |
|   - Public Guests: Safari / Chrome Mobile & Desktop                           |
|   - Hotel Staff & Ops: Tablets, Desktops, Front Desk POS Terminals            |
+-------------------------------------------------------------------------------+
                                      │
                                      ▼ HTTPS / REST / Inertia Protocol
+-------------------------------------------------------------------------------+
|                           LARAVEL APPLICATION SERVER                          |
|                                                                               |
|  [ HTTP Routing & Middleware ]                                                |
|    - CSRF Protection, Rate Limiting, RBAC & Role Gates, Session Auth          |
|                                                                               |
|  [ Controllers & API Endpoints ]                                              |
|    - BookingEngineController    - FrontDeskController    - FolioController    |
|    - PesapalPaymentController   - HousekeepingController - SpaController      |
|    - DiningController           - EventSalesController   - CmsController      |
|                                                                               |
|  [ Domain Services Layer ]                                                    |
|    - AvailabilityEngineService (Calculates physical inventory & holds)        |
|    - PesapalV3PaymentService (OAuth2, order submission, IPN handler)          |
|    - FolioSettlementService (Multi-outlet billing, taxes, receipts)           |
|    - NotificationDispatcher (In-app, Mail, SMS/WhatsApp queues)               |
|                                                                               |
|  [ Eloquent ORM & Query Scopes ]                                              |
|    - RoomType, Room, Booking, Folio, Payment, GuestProfile, CashierShift      |
+-------------------------------------------------------------------------------+
                                      │
                                      ▼
+-------------------------------------------------------------------------------+
|                            DATABASE & STORAGE LAYER                           |
|   - SQLite (Local Dev / Portable) & MySQL 8.0+ / MariaDB (cPanel Production)  |
|   - Local / S3 File Storage for Media Library, PDF Receipts & Vouchers        |
+-------------------------------------------------------------------------------+
```

---

## 2. Key Technology Choices

- **Backend Framework:** Laravel 11.x (PHP 8.4+ compatible). Ensures rapid development, rock-solid security, robust database migrations, and clean queue/cron handling.
- **Frontend Architecture:** Inertia.js + React 18 + TypeScript. Provides rich reactive single-page app UX without complex separate microservice API overheads.
- **Styling:** Tailwind CSS 4 with custom luxury hospitality tokens.
- **Payment Processing:** Pesapal 3.0 API with server-to-server IPN verification.
- **Storage:** Local protected storage with symbolic links (`php artisan storage:link`) or S3 adapter.
- **Hosting Compatibility:** Standard cPanel hosting (Apache/Nginx with PHP-FPM and MySQL) without requiring permanent Node.js daemon processes in production.