# Architecture

## Goal

Refactor PHarking into a Laravel 12 codebase with:

- Blade public pages
- Livewire-powered dashboards and directory filters
- Filament admin panel
- Thin controllers/components with reusable business logic
- Migration-first database with factories/seeders
- API-ready service layer for V2 mobile

## Domain Boundaries

1. Identity & Access
   - `User`
   - `HostProfile`
   - Role/Status policies (`admin|host|member`, `active|suspended`)
2. Listings
   - `Listing`
   - `ListingPhoto`
   - `Amenity` + pivot
3. Availability
   - `AvailabilityRule` (weekly recurring windows)
   - `AvailabilityException` (date overrides/blocks)
4. Booking
   - `Booking`
   - `BookingPayment`
   - overlap prevention + lifecycle transitions
5. Engagement
   - `Favorite`
   - `Review`
6. Optional Profile Assets
   - `Vehicle` (V2-ready)

## Intended Folder Structure

```text
app/
  Actions/
    Booking/
    Listing/
    Availability/
  Services/
    Availability/
    Pricing/
  DTOs/
  Http/
    Controllers/
      Web/
      Api/V1/
    Requests/
      Listing/
      Booking/
      Profile/
    Resources/
      V1/
  Livewire/
    Directory/
    Member/
    Host/
  Models/
  Policies/
database/
  factories/
  migrations/
  seeders/
resources/views/
  layouts/
  public/
  member/
  host/
  livewire/
routes/
  web.php
  api.php
```

## Application Layers

1. Transport Layer
   - Web controllers + Livewire components + API controllers
   - Input validation handled by Form Requests (and Livewire rules)
2. Domain/Use-Case Layer
   - Actions orchestrate use-cases (`CreateBookingAction`, `PublishListingAction`, etc.)
   - Services perform reusable calculations/computations (availability, totals)
3. Persistence Layer
   - Eloquent models + query scopes + relationships
   - Database constraints + indexes + transactions for consistency

## Controller/Livewire Rules

- Controllers return views/resources and call actions only.
- Livewire components keep UI state + delegate business work to actions/services.
- No raw SQL in controllers/components unless narrowly justified.

## Authorization Model

- Policies for listing/booking/profile/admin access:
  - `ListingPolicy`
  - `BookingPolicy`
  - `HostProfilePolicy`
- Middleware + gates for role-based dashboard/admin access.

## API V1 Readiness

- Initial endpoints:
  - `GET /api/v1/listings`
  - `GET /api/v1/listings/{listing}`
- JsonResource responses in `app/Http/Resources/V1`.
- Sanctum installed for future token auth expansion.
- Business logic remains in actions/services so web + API share behavior.

## Non-Functional Standards

- Money stored as integer cents + currency code.
- Booking timestamps persisted in UTC (`start_at`, `end_at`).
- Eager loading for dashboard/index views to avoid N+1.
- Testability prioritized with isolated actions and factories.