# Architecture Overview

Turista is an API-first Laravel 13 application. It exposes a JSON REST API under `/api/v1` and keeps frontend assets minimal.

## High-level components

```
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Client    │────▶│  Nginx/PHP   │────▶│  Laravel App    │
│  (SPA/App)  │◀────│   (Laravel)  │◀────│                 │
└─────────────┘     └──────────────┘     └─────────────────┘
                                                  │
           ┌────────────┬────────────┬────────────┼────────────┬────────────┐
           ▼            ▼            ▼            ▼            ▼            ▼
      Routes/      Controllers/    Services/    Models/     Policies/     Jobs/
      Middleware   Requests/       Facades      Eloquent    Gates         Notifications
                 Resources                     MySQL
```

## Tech stack

| Layer | Technology |
|-------|------------|
| Framework | Laravel 13 |
| Language | PHP 8.4 |
| Database | MySQL 8.0 (dev), SQLite in-memory (tests) |
| API authentication | Laravel Sanctum |
| Roles & permissions | Spatie Laravel Permission |
| Media uploads | Spatie Media Library |
| Auditing | OwenIt Auditing |
| Frontend build | Vite + Tailwind CSS 4 |
| Testing | Pest PHP 4 |
| Queues | Database (default) |

## Design principles

1. **Thin controllers, fat services.** Controllers validate input, authorize actions, and delegate business logic to service classes in `app/Services/`. Services are exposed through facades in `app/Facades/`.

2. **Policy-based authorization.** Every resource has a policy in `app/Policies/`. Route middleware checks roles; policies check ownership and state. `super_admin` bypasses all policy checks via `Gate::before`.

3. **Availability ledger.** The `unit_availabilities` table stores one row per unit per night. This makes date-range conflict checks simple and reliable.

4. **Invoice/receipt mirroring.** When a reservation is created or modified, the system generates an owner-facing invoice and a customer-facing receipt with matching financial totals.

5. **Scheduled notifications.** Reminders are stored as `ScheduledNotification` rows and dispatched by a scheduled command through queue jobs.

6. **Morph relationships.** `Reservation` and `PendingReservation` are polymorphically linked to either a `Customer` or a `PendingCustomer`, supporting both online and on-arrival booking flows.

## Key entry points

- **HTTP API:** `routes/api.php`
- **Console commands:** `routes/console.php`
- **Exception handling:** `bootstrap/app.php`
- **Service container bindings:** `app/Providers/AppServiceProvider.php`