# Turista API — Full Documentation Design

**Date:** 2026-06-27  
**Topic:** Full project documentation suite  
**Status:** Approved for implementation

---

## 1. Goal

Create a comprehensive, navigable documentation suite in `docs/` that helps developers, API consumers, and operators understand, run, and maintain the Turista API.

## 2. Context

Turista is a Laravel 13 API for vacation-rental management. It already has:

- A concise `README.md` with quick-start commands.
- `PROJECT_PROGRESS.md`, `REMAINING_FIXES.md`, and a detailed `security-audit-2026-06-22.md`.
- Laravel Request Docs installed for auto-generated API reference.
- A complex domain model (users/profiles, buildings/units, reservations, billing, promo codes, locations, notifications).

The existing documents are useful but fragmented. A unified documentation suite will lower onboarding time and reduce support questions.

## 3. Approaches Considered

### 3.1 README-only expansion
- **Description:** Expand `README.md` to include architecture, API, and operational details.
- **Pros:** Single file, low friction.
- **Cons:** Becomes unwieldy for a project of this size; hard to navigate and maintain.

### 3.2 Structured markdown documentation in `docs/`
- **Description:** Split documentation into focused guides (architecture, API, domains, development, operations, security).
- **Pros:** Maintainable, easy to navigate, can grow with the project, searchable.
- **Cons:** More initial effort than a single README.

### 3.3 Auto-generated docs + minimal manual guides
- **Description:** Rely on Laravel Request Docs for API details and write only a short developer guide.
- **Pros:** API docs stay in sync automatically.
- **Cons:** Misses architecture and domain context; API docs require a running application.

## 4. Recommended Approach

**Adopt approach 3.2 — structured markdown documentation in `docs/`.**

Laravel Request Docs will be referenced for exhaustive endpoint schemas, but the manual docs will provide the context, examples, and operational guidance that auto-generated docs cannot.

## 5. Proposed Documentation Structure

```
docs/
├── README.md                          # Documentation index and navigation
├── architecture/
│   ├── overview.md                    # High-level architecture & design principles
│   ├── directory-structure.md         # What lives where
│   ├── authentication.md              # Sanctum, roles, permissions
│   ├── data-flow.md                   # Request lifecycle & service layer
│   └── error-handling.md              # Exception mapping & response format
├── api/
│   ├── overview.md                    # Base URL, auth, content-type, rate limits
│   ├── authentication.md              # Login, register, OTP, password reset
│   ├── roles/
│   │   ├── admin.md
│   │   ├── owner.md
│   │   ├── employee.md
│   │   └── customer.md
│   └── auto-generated.md              # How to use Laravel Request Docs
├── domains/
│   ├── users-and-profiles.md
│   ├── buildings-and-units.md
│   ├── reservations.md
│   ├── billing.md
│   ├── promo-codes.md
│   ├── locations.md
│   └── notifications.md
├── development/
│   ├── setup.md                       # Local installation step-by-step
│   ├── testing.md                     # Running tests, writing tests
│   ├── code-style.md                  # Pint, conventions
│   └── common-tasks.md                # Seeding, commands, troubleshooting
├── operations/
│   ├── deployment.md                  # Production checklist
│   ├── environment-variables.md       # .env reference
│   ├── scheduled-tasks.md             # Console commands & schedulers
│   └── monitoring.md                  # Logs, audits, queues
└── security/
    ├── overview.md                    # Security model & assumptions
    ├── audit-report-summary.md        # Condensed security audit findings
    └── checklist.md                   # Pre-launch security checklist
```

## 6. Key Content Decisions

- **API reference:** Provide a curated overview of endpoints by role and link to Laravel Request Docs (`/request-docs`) for full request/response schemas. Avoid duplicating auto-generatable endpoint details.
- **Architecture docs:** Explain the service layer, policy-based authorization, availability ledger, invoice/receipt mirroring, scheduled notifications, and sequence numbering.
- **Domain docs:** Each core business domain gets a dedicated file with models, relationships, lifecycle, and key business rules.
- **Security docs:** Include a summary of the existing security audit, the intentional `Model::unguard()` decision, and a launch checklist.
- **Developer/operations docs:** Cover setup, testing, code style, deployment, env vars, scheduled tasks, and monitoring.

## 7. Success Criteria

- A new developer can set up the project, run tests, and understand where to add features by reading the docs.
- An API consumer can authenticate and find the right endpoints for their role.
- An operator knows the env vars, scheduled tasks, and security considerations for deployment.

## 8. Implementation Notes

- All new documentation files will be written in Markdown.
- Existing documents (`README.md`, `PROJECT_PROGRESS.md`, `REMAINING_FIXES.md`, `security-audit-2026-06-22.md`) will remain in place; the new `docs/README.md` will link to them.
- No code changes are required for the documentation itself.
- After writing, verify internal links and run a quick consistency check.