# Turista API Full Documentation — Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or implement inline task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Create a complete, navigable Markdown documentation suite in `docs/` covering architecture, API usage, business domains, development workflow, operations, and security. **Architecture:** The docs are organized by audience and concern (architecture, API, domains, development, operations, security) with a central `docs/README.md` index. API details that are auto-generated by Laravel Request Docs are referenced rather than duplicated. **Tech Stack:** Markdown only; no code changes required. --- ## File Structure All files live under `docs/` and are written in Markdown. | Path | Responsibility | |------|----------------| | `docs/README.md` | Landing page, navigation, quick links | | `docs/architecture/overview.md` | High-level architecture & design principles | | `docs/architecture/directory-structure.md` | Directory layout and what each top-level folder contains | | `docs/architecture/authentication.md` | Sanctum tokens, roles, permissions, guards | | `docs/architecture/data-flow.md` | Request lifecycle, service layer, facade pattern | | `docs/architecture/error-handling.md` | Exception mapping, HTTP response shapes | | `docs/api/overview.md` | Base URL, versioning, content type, rate limits, errors | | `docs/api/authentication.md` | Login, registration, OTP, password reset, logout | | `docs/api/roles/admin.md` | Admin endpoints overview | | `docs/api/roles/owner.md` | Owner endpoints overview | | `docs/api/roles/employee.md` | Employee endpoints overview | | `docs/api/roles/customer.md` | Customer endpoints overview | | `docs/api/auto-generated.md` | How to generate and read Laravel Request Docs | | `docs/domains/users-and-profiles.md` | User, Owner, Employee, Customer, PendingCustomer | | `docs/domains/buildings-and-units.md` | Buildings, units, facilities, availability ledger | | `docs/domains/reservations.md` | Reservation lifecycle, on-arrival flow, check-in/out | | `docs/domains/billing.md` | Invoices, receipts, transactions, wallet, sequences | | `docs/domains/promo-codes.md` | Bulk generation, validation, redemption | | `docs/domains/locations.md` | Countries, cities, regions, currencies | | `docs/domains/notifications.md` | Scheduled reminders, database/WhatsApp channels | | `docs/development/setup.md` | Step-by-step local setup | | `docs/development/testing.md` | Running and writing Pest tests | | `docs/development/code-style.md` | Laravel Pint, naming conventions | | `docs/development/common-tasks.md` | Useful artisan commands, seeders, troubleshooting | | `docs/operations/deployment.md` | Production deployment checklist | | `docs/operations/environment-variables.md` | `.env` reference table | | `docs/operations/scheduled-tasks.md` | Console commands and scheduler entries | | `docs/operations/monitoring.md` | Logs, audits, queues, health checks | | `docs/security/overview.md` | Security model, authz, assumptions | | `docs/security/audit-report-summary.md` | Condensed findings from `docs/security-audit-2026-06-22.md` | | `docs/security/checklist.md` | Pre-launch security checklist | --- ## Task 1: Create Documentation Index **Files:** - Create: `docs/README.md` - [ ] **Step 1: Write `docs/README.md`** Content must include: - Project name and one-line description. - Link to top-level `README.md` for quick start. - Table of contents linking to every file listed in the File Structure above. - Audience guidance ("New developer start here", "API consumer start here", "Operator start here"). - Link to existing `PROJECT_PROGRESS.md`, `REMAINING_FIXES.md`, and `security-audit-2026-06-22.md`. --- ## Task 2: Create Architecture Docs **Files:** - Create: `docs/architecture/overview.md` - Create: `docs/architecture/directory-structure.md` - Create: `docs/architecture/authentication.md` - Create: `docs/architecture/data-flow.md` - Create: `docs/architecture/error-handling.md` - [ ] **Step 2.1: Write `docs/architecture/overview.md`** Content must include: - What Turista is (Laravel 13 API for vacation rentals). - High-level components: API controllers, service layer, Eloquent models, policies, queues, scheduled tasks. - Key design principles: thin controllers, service facades, policy-based authorization, availability ledger, invoice/receipt mirroring. - Tech stack table (Laravel 13, PHP 8.4, MySQL, Vite, Tailwind, Pest, Sanctum, Spatie Permission/MediaLibrary, OwenIt Auditing). - [ ] **Step 2.2: Write `docs/architecture/directory-structure.md`** Content must include: - Table mapping each top-level directory (`app/`, `database/`, `routes/`, `config/`, `tests/`, `resources/`, `docs/`) to its purpose. - Sub-sections for `app/Http/Controllers/`, `app/Http/Requests/`, `app/Http/Resources/`, `app/Models/`, `app/Services/`, `app/Policies/`, `app/Jobs/`, `app/Notifications/`, `database/migrations/`, `database/seeders/`. - [ ] **Step 2.3: Write `docs/architecture/authentication.md`** Content must include: - Sanctum stateless token flow (login → token → authenticated requests). - Token expiration (1 week from `config/sanctum.php`). - Roles and permissions seeded by `RolesAndPermissionsSeeder`. - Guards (`api` default, `web` for Spatie compatibility). - `EnsureUserIsVerified` middleware. - `Gate::before` super-admin bypass. - [ ] **Step 2.4: Write `docs/architecture/data-flow.md`** Content must include: - HTTP request lifecycle: route → middleware → Form Request validation → controller → policy → service → model → resource response. - Service layer pattern and facades in `app/Facades/`. - Availability ledger design (`unit_availabilities` one row per unit per night). - Scheduled notification flow (scheduler → command → job → notification channels). - Sequence numbering for documents. - [ ] **Step 2.5: Write `docs/architecture/error-handling.md`** Content must include: - JSON exception rendering configured in `bootstrap/app.php`. - Validation, authentication, model-not-found, HTTP exception response shapes. - `ReservationUnavailableException` usage. - Consistent error envelope format. --- ## Task 3: Create API Docs **Files:** - Create: `docs/api/overview.md` - Create: `docs/api/authentication.md` - Create: `docs/api/roles/admin.md` - Create: `docs/api/roles/owner.md` - Create: `docs/api/roles/employee.md` - Create: `docs/api/roles/customer.md` - Create: `docs/api/auto-generated.md` - [ ] **Step 3.1: Write `docs/api/overview.md`** Content must include: - Base URL `/api/v1`. - `Accept: application/json` and `Authorization: Bearer {token}` headers. - Rate limits on public auth routes. - Standard pagination, sorting, and filtering conventions. - Link to Laravel Request Docs for exhaustive schemas. - [ ] **Step 3.2: Write `docs/api/authentication.md`** Content must include: - Login endpoint and response. - Owner/customer registration and OTP verification. - Resend OTP, forgot password, reset password, update password, logout. - Note that OTPs appear in responses only in `local`/`testing` environments. - [ ] **Step 3.3: Write role endpoint overviews** For each file (`admin.md`, `owner.md`, `employee.md`, `customer.md`), include: - Required role and typical middleware. - Functional groups (e.g., for owner: dashboard, profile, buildings, units, employees, reservations, billing, promo codes, availability). - Key endpoints with HTTP verb and path. - Cross-reference to `docs/domains/` for business rules. - [ ] **Step 3.4: Write `docs/api/auto-generated.md`** Content must include: - What Laravel Request Docs is and where it is configured. - How to enable it (`REQUEST_DOCS_ENABLED=true`). - URL path `/request-docs`. - How to regenerate `api.json` / `routes.json` if needed. - Security note: keep it disabled in production. --- ## Task 4: Create Domain Docs **Files:** - Create: `docs/domains/users-and-profiles.md` - Create: `docs/domains/buildings-and-units.md` - Create: `docs/domains/reservations.md` - Create: `docs/domains/billing.md` - Create: `docs/domains/promo-codes.md` - Create: `docs/domains/locations.md` - Create: `docs/domains/notifications.md` - [ ] **Step 4.1: Write `docs/domains/users-and-profiles.md`** Content must include: - `User` model as shared identity. - `Owner`, `Employee`, `Customer`, `PendingCustomer` profiles. - Approval/verification flows for owners and pending customers. - Role-specific fields and relationships. - [ ] **Step 4.2: Write `docs/domains/buildings-and-units.md`** Content must include: - Building model, status, photos, facilities, booking conditions. - Unit model, pricing, guest limits, photos, facilities. - Bulk unit creation. - Availability ledger (`UnitAvailability`) and blocking. - Public catalog filters. - [ ] **Step 4.3: Write `docs/domains/reservations.md`** Content must include: - Reservation lifecycle: pending → confirmed → checked_in → checked_out / canceled. - Customer online booking vs. owner/employee on-arrival booking. - Pending reservation OTP flow. - Date changes and refund handling. - Check-in/check-out actions. - [ ] **Step 4.4: Write `docs/domains/billing.md`** Content must include: - Invoice generation for owners. - Receipt generation for customers. - Payments/refunds and wallet balance. - Transaction types and methods. - Sequence numbering for invoices/receipts/reservations. - [ ] **Step 4.5: Write `docs/domains/promo-codes.md`** Content must include: - Bulk generation by owners. - Code hashing and encryption. - Validation rules (limits, dates, unit eligibility). - Redemption during reservation calculation. - [ ] **Step 4.6: Write `docs/domains/locations.md`** Content must include: - Country, City, Region, Currency models. - Admin CRUD vs. public read-only indexes. - Location seeder and `locations:download` command. - [ ] **Step 4.7: Write `docs/domains/notifications.md`** Content must include: - `ScheduledNotification` model and scheduler. - `ReservationReminder` notification. - Database and WhatsApp channels. - Cancellation rules for checked-out/canceled reservations. --- ## Task 5: Create Development Docs **Files:** - Create: `docs/development/setup.md` - Create: `docs/development/testing.md` - Create: `docs/development/code-style.md` - Create: `docs/development/common-tasks.md` - [ ] **Step 5.1: Write `docs/development/setup.md`** Content must include: - Prerequisites (PHP 8.4+, Composer 2.9+, MySQL 8.0+, Node 20+, NPM 10+). - Install commands (`composer install`, `npm install`, `cp .env.example .env`, `php artisan key:generate`, `php artisan storage:link`, `php artisan migrate --seed`, `npm run build`). - Running the dev stack (`composer run dev`). - [ ] **Step 5.2: Write `docs/development/testing.md`** Content must include: - Running Pest (`php artisan test`). - Test database (SQLite in-memory via `phpunit.xml`). - Test structure (`tests/Feature`, `tests/Unit`). - `TestCase` helpers and fakes. - [ ] **Step 5.3: Write `docs/development/code-style.md`** Content must include: - Laravel Pint (`vendor/bin/pint --test`). - Running Pint and applying fixes. - Naming and organizational conventions. - [ ] **Step 5.4: Write `docs/development/common-tasks.md`** Content must include: - Creating a super admin (`admin:create-super`). - Downloading locations (`locations:download`). - Releasing expired pending reservations. - Sending due notifications. - Common troubleshooting (MySQL cache table, config cache, queue worker). --- ## Task 6: Create Operations Docs **Files:** - Create: `docs/operations/deployment.md` - Create: `docs/operations/environment-variables.md` - Create: `docs/operations/scheduled-tasks.md` - Create: `docs/operations/monitoring.md` - [ ] **Step 6.1: Write `docs/operations/deployment.md`** Content must include: - Production `.env` checklist (debug off, docs disabled, CORS restricted). - Build steps (`npm run build`, `php artisan optimize`, `php artisan route:cache`). - Queue worker and scheduler setup. - Storage link and permissions. - [ ] **Step 6.2: Write `docs/operations/environment-variables.md`** Content must include: - Table of env vars grouped by concern (app, database, sanctum, mail, CoreVerde WhatsApp, request docs, CORS, locations). - Default values and whether they are required in production. - [ ] **Step 6.3: Write `docs/operations/scheduled-tasks.md`** Content must include: - Commands in `routes/console.php` (`notifications:send-due`, `pending-reservations:release-expired`). - How to configure the cron entry for `schedule:run`. - Command descriptions and frequency. - [ ] **Step 6.4: Write `docs/operations/monitoring.md`** Content must include: - Log location (`storage/logs`). - Audit log (`audits` table). - Queue monitoring. - Health check endpoint (`/` from `routes/web.php`). - Error tracking recommendations. --- ## Task 7: Create Security Docs **Files:** - Create: `docs/security/overview.md` - Create: `docs/security/audit-report-summary.md` - Create: `docs/security/checklist.md` - [ ] **Step 7.1: Write `docs/security/overview.md`** Content must include: - Defense-in-depth summary. - Authn/authz model. - Mass-assignment decision (`Model::unguard()` is intentional). - OTP and token handling. - Upload and output-encoding assumptions. - [ ] **Step 7.2: Write `docs/security/audit-report-summary.md`** Content must include: - Condensed findings from `docs/security-audit-2026-06-22.md`. - Status of each finding (fixed / retained / accepted risk). - Positive findings. - [ ] **Step 7.3: Write `docs/security/checklist.md`** Content must include: - Pre-launch checklist covering: debug mode, request docs, CORS, security headers, token TTL, env vars, default credentials, dependency updates, file uploads, OTP exposure, login enumeration. --- ## Task 8: Verify Documentation **Files:** - Modify: `docs/README.md` if any links are broken after creation. - [ ] **Step 8.1: Link check** Run a script or manually verify that all internal Markdown links in `docs/README.md` and cross-references between docs point to files that exist. - [ ] **Step 8.2: Consistency review** Skim every new file and fix: - Typos. - Inconsistent env var names. - Outdated references to `web` guard (project now uses `api`). - Contradictions with `README.md` or `PROJECT_PROGRESS.md`. --- ## Spec Coverage Check | Spec Section | Implementing Task | |--------------|-------------------| | Central navigation index | Task 1 | | Architecture docs | Task 2 | | API docs (overview + roles + auto-generated reference) | Task 3 | | Domain docs | Task 4 | | Development docs | Task 5 | | Operations docs | Task 6 | | Security docs | Task 7 | | Verification | Task 8 | ## Placeholder Scan - No `TBD`, `TODO`, or `implement later` strings. - Each file path is exact. - Each task names concrete content sections. - No references to undefined types or methods.