# Data Flow

This document describes how a typical HTTP request moves through the Turista application.

## Standard request lifecycle

```
Request
  ▼
Route (routes/api.php)
  ▼
Middleware (auth, verified, role, throttle)
  ▼
Form Request validation (app/Http/Requests/)
  ▼
Controller action (app/Http/Controllers/)
  ▼
Policy authorization ($this->authorize('view', $model))
  ▼
Service layer (app/Services/ via Facades)
  ▼
Eloquent models & database
  ▼
API Resource (app/Http/Resources/)
  ▼
JSON response
```

## Example: creating a reservation

1. **Route.** `POST /api/v1/customer/reservations` hits `ReservationController@store`.
2. **Middleware.** `auth:api` and `role:customer` ensure an authenticated customer.
3. **Validation.** `ReservationRequest` validates dates, guest counts, `unit_id`, and promo code.
4. **Controller.** The controller calls `ReservationService::createReservationForCustomer()`.
5. **Service logic.**
   - Looks up the unit and checks availability via `UnitAvailabilityService`.
   - Validates the promo code via `PromoCodeService`.
   - Calculates the total price.
   - Creates the `Reservation` record.
   - Books availability dates.
   - Generates an `Invoice` for the owner and a `Receipt` for the customer.
   - Schedules reminder notifications via `ReservationReminderScheduler`.
6. **Response.** A `ReservationResource` is returned with the new reservation, invoice, and receipt.

## Service layer and facades

Business logic lives in `app/Services/` and is consumed through facades in `app/Facades/`. This keeps controllers thin and makes the logic testable in isolation.

| Service | Responsibility |
|---------|----------------|
| `ReservationService` | Reservation lifecycle, pricing, availability booking, documents. |
| `PaymentService` | Payments, refunds, wallet updates. |
| `UnitAvailabilityService` | Date ledger operations (book, hold, release, block). |
| `PromoCodeService` | Bulk generation and redemption validation. |
| `OtpService` | OTP generation, caching, and verification. |
| `WhatsAppService` | CoreVerde WhatsApp HTTP integration. |
| `DashboardMetrics` | Revenue, occupancy, and user-growth aggregations. |
| `FilterService` | Query filtering for list endpoints. |
| `SequenceService` | Atomic document number generation. |
| `ReservationReminderScheduler` | Schedules reminder notifications. |

## Availability ledger

`unit_availabilities` has one row per unit per night with a `status` of `available`, `blocked`, or `booked`. When a reservation is created, the service changes the matching rows to `booked` and links them to the reservation. Cancellations reverse this process.

## Scheduled notifications

When a reservation is confirmed, `ReservationReminderScheduler` creates `ScheduledNotification` rows for check-in, check-out, and evacuate reminders. The `notifications:send-due` scheduler command runs every minute and dispatches `DispatchScheduledNotification` jobs for due rows. The job sends the notification through the database channel (in-app notification) and WhatsApp channel.

## Sequence numbering

`SequenceService` increments counters stored in the `sequences` table to produce zero-padded document numbers such as `INV-00001`, `REC-00001`, and `RES-00001`.

## Error propagation

Controllers catch domain exceptions (e.g., `ReservationUnavailableException`) and return structured JSON errors. Unexpected exceptions are rendered as JSON by the handler in `bootstrap/app.php`.