# Directory Structure

This document explains the purpose of each major directory and file group in the Turista project.

## Top level

| Path | Purpose |
|------|---------|
| `app/` | Application code (controllers, models, services, etc.). |
| `bootstrap/` | Laravel bootstrapping and exception handling. |
| `config/` | Configuration files. |
| `database/` | Migrations, seeders, factories, and location data. |
| `docs/` | Project documentation (this suite). |
| `public/` | Web server document root. |
| `resources/` | CSS, JS, and email views. |
| `routes/` | Route definitions. |
| `storage/` | Logs, cache, uploads, and compiled files. |
| `tests/` | Pest feature and unit tests. |
| `vendor/` | Composer dependencies. |
| `node_modules/` | NPM dependencies. |

## `app/`

| Path | Purpose |
|------|---------|
| `Console/Commands/` | Artisan commands (`CreateSuperAdmin`, `DownloadLocations`, `ReleaseExpiredPendingReservations`, `SendDueScheduledNotifications`). |
| `Exceptions/` | Custom exceptions such as `ReservationUnavailableException`. |
| `Facades/` | Laravel facades for services (`ReservationService`, `PaymentService`, `FilterService`, etc.). |
| `Http/Controllers/` | HTTP controllers grouped by area (API auth, admin, owner, customer, core resources). |
| `Http/Middleware/` | Custom middleware (`EnsureUserIsVerified`, `SecurityHeadersMiddleware`). |
| `Http/Requests/` | Form request classes for validation. |
| `Http/Resources/` | API resource transformers. |
| `Jobs/` | Queue jobs (`DispatchScheduledNotification`). |
| `Mail/` | Mailable classes (`PasswordResetMail`). |
| `Models/` | Eloquent models. |
| `Notifications/` | Notification classes and custom channels (database, WhatsApp). |
| `Policies/` | Authorization policies for every major model. |
| `Providers/` | Service providers (`AppServiceProvider`, etc.). |
| `Rules/` | Custom validation rules (`PhoneNumber`, `WhatsAppNumber`, `PhotoFileRules`). |
| `Services/` | Business logic services (`ReservationService`, `PaymentService`, `FilterService`, etc.). |
| `Traits/` | Reusable traits (`HandlesMediaPhotos`). |

## `database/`

| Path | Purpose |
|------|---------|
| `data/` | JSON/PHP location data used by seeders. |
| `factories/` | Model factories for tests and seeding. |
| `migrations/` | All database migrations, ordered by timestamp. |
| `seeders/` | `DatabaseSeeder`, `RolesAndPermissionsSeeder`, `LocationSeeder`. |

## `routes/`

| File | Purpose |
|------|---------|
| `api.php` | All API routes (prefixed with `/api/v1`). |
| `console.php` | Scheduled console commands. |
| `web.php` | Minimal web routes (health check, password-reset email view). |

## `resources/`

| Path | Purpose |
|------|---------|
| `css/app.css` | Tailwind CSS import. |
| `js/app.js` | Minimal Vite entry point. |
| `views/emails/password-reset.blade.php` | Password reset email template. |

## `tests/`

| Path | Purpose |
|------|---------|
| `Feature/` | High-level HTTP/feature tests. |
| `Unit/` | Isolated unit tests for services, policies, and models. |
| `Pest.php` | Pest configuration; applies `RefreshDatabase` to feature/unit tests. |
| `TestCase.php` | Base test case with shared helpers and CoreVerde fakes. |

## `config/`

Key files include:

- `app.php` — application name, environment, timezone, locale.
- `auth.php` — default `api` guard and password reset settings.
- `sanctum.php` — token expiration and stateful domains.
- `audit.php` — OwenIt Auditing configuration.
- `request-docs.php` — Laravel Request Docs settings.
- `locations.php` — countries to seed.