# HotelSync Documentation Index

**Last updated:** 2026-04-27 (API docs rebuilt from Postman collection)
**Source of truth for API:** Public Postman collection (`HotelSync Public API`). Every endpoint, request body, and response example is taken from real, working calls.
**Coverage:** 136 endpoints across 28 folders, all with markdown + PDF.

Every `.md` file in this tree has a sibling `.pdf` for offline reading.

## Quick links

- **Browse the API (recommended):** open [`api/redoc.html`](./api/redoc.html) in a browser — Redoc renderer, body parameters shown as a flat readable list with types, required flags, descriptions, enum values. Self-contained, opens directly from disk.
- **Alternative renderer:** [`api/swagger-ui.html`](./api/swagger-ui.html) — Swagger UI with "Try it out" support. (Click the "Schema" tab next to "Example Value" to see body fields.)
- **API spec (OpenAPI 3.1):** [`api/openapi.yaml`](./api/openapi.yaml) — 136 paths, all per-property schemas, real request/response examples.
- **Per-folder API docs:** [`api/README.md`](./api/README.md) — links into all 28 folders.
- **Architecture maps:** [`backend/architecture.md`](./backend/architecture.md) (PHP backend), [`frontend/architecture.md`](./frontend/architecture.md) (Vue 3 SPA).
- **Security risk register:** [`findings/initial-risks.md`](./findings/initial-risks.md) — CRITICAL / HIGH / MEDIUM / LOW grouped.

---

## Project Summary

**HotelSync** is a SaaS hotel/property management platform. Custom PHP backend, Vue 3 SPA frontend. Heavy integration with channel managers (Channex), payment gateways (Stripe, Razorpay, Axcessms), and communication services (InfoBip, SendGrid, OneSignal, Intercom).

**Codebase scale:**
- ~1,165 PHP files (backend + crons + utilities)
- ~643 Vue components, 47 Pinia stores (frontend)
- ~95 cron scripts
- 136 documented public REST endpoints (Postman) — broader internal API surface exists in `api/` folder

**Tech stack:**
- Backend: PHP 7.4+, mysqli, Composer (Firebase JWT, Stripe, Razorpay, Treblle, SendGrid)
- Frontend: Vue 3.5, Vite 6, Pinia 2.3, Vue Router 4.5, PrimeVue 3
- Database: MySQL with stored procedures
- Services: Channex, Stripe, Razorpay, InfoBip, Treblle, SendGrid, OneSignal

---

## Documentation Tree

```
docs/
├── README.md / README.pdf         (this file)
├── verification-report.md / .pdf  (architecture-docs accuracy report)
│
├── backend/
│   └── architecture.md / .pdf     (request lifecycle, folder map, DB, auth, integrations)
│
├── frontend/
│   └── architecture.md / .pdf     (bootstrap, router, Pinia stores, axios, i18n, components)
│
├── api/
│   ├── README.md / .pdf           (top-level API index, links into all 28 folders)
│   ├── openapi.yaml               (OpenAPI 3.1 — full spec, 136 paths)
│   ├── swagger-ui.html            (self-contained browser for the spec)
│   │
│   └── <one folder per Postman folder, 28 folders total>
│       ├── README.md / .pdf       (folder index)
│       └── <endpoint>.md / .pdf   (per-endpoint reference)
│
└── findings/
    ├── initial-risks.md / .pdf    (consolidated, severity-grouped)
    ├── risks-backend.md / .pdf    (28 backend issues)
    ├── risks-frontend.md / .pdf   (12 Vue SPA issues)
    └── risks-api.md / .pdf        (23 API surface issues)
```

---

## How to use these docs

### Calling the API (developer)
1. Open `api/swagger-ui.html` in a browser to explore.
2. Find the endpoint you need under `api/<folder>/<endpoint>.md` for full curl + request/response.
3. For programmatic clients, point any OpenAPI-compatible generator at `api/openapi.yaml`.

### Onboarding a new backend dev
1. `backend/architecture.md` — request lifecycle, folder layout, DB patterns, auth.
2. `api/README.md` — pick a folder relevant to your area, skim its README.
3. `findings/risks-backend.md` — what NOT to do (SQL injection patterns, missing auth, hardcoded secrets).

### Onboarding a new frontend dev
1. `frontend/architecture.md` — bootstrap, router, state, axios, i18n.
2. `api/README.md` — endpoints the frontend calls (look for ones the SPA already uses).
3. `findings/risks-frontend.md` — XSS via translation HTML decoding, PrimeVue version mismatch, code splitting gap.

### Security review
1. `findings/initial-risks.md` — start here, severity-grouped.
2. Drill into the per-stack files for detailed findings + fixes.
3. Each item cites file:line so claims can be cross-checked against source.

### Generating clients / Postman collections from the spec
- `api/openapi.yaml` is OpenAPI 3.1, valid, 0 broken refs. Drop into:
  - `openapi-generator-cli` for typed clients in any language
  - Postman → Import → File → openapi.yaml
  - Stoplight, Redocly, Scalar — any modern OpenAPI viewer

---

## Things to know

### Authentication
- **Login:** `POST /api/user/auth/login` with `{ token, username, password, remember }`. Response includes a `pkey` field — that's the session key for subsequent calls.
- **Per-request auth:** all subsequent endpoints take `key` in the JSON body, set to the `pkey` value from login.
- **Partner token:** the `token` field in the login body is a long-lived partner identifier. Request from HotelSync support.

### Multi-action URL pattern
The backend dispatches by URL path: `/api/<feature>/<verb>/<action>` — e.g. `/api/avail/edit/avail`, `/api/calendar/data/calendar`. Each unique URL is a distinct OpenAPI operation.

### Saved response examples contain real data
The Postman collection includes saved response examples that contain real account data (names, emails, password hash, session pkey, property IDs for one Djordje user account). This data is already public via the published Postman docs. If that's a concern, regenerate the collection's saved examples with synthetic data and re-run this docs build.

### URL bases observed in the collection
- `https://app.otasync.me` — production (most endpoints)
- `https://beta.otasync.me` — beta (a few)
- `https://newdb.otasync.me/` — collection variable default
- `http://localhost/otasync-db/` — appeared in one `calendar/edit/dates` example

The OpenAPI spec lists all three production-like servers under `servers:`.

---

## What's NOT in here

- **Database schema** — no ER diagram, no stored procedure docs yet. The `checkUser`, `checkProperty`, `getReservations` etc. helpers reference SPs we haven't documented.
- **Internal admin