# Visit Syria: remaining API plan

Audit of `../backend/routes/api.php` (`/api/v1`) against what the website calls today. Follows the conventions in `API_INTEGRATION_PLAN.md` (client in `src/lib/api/client.ts`, one `src/lib/api/<x>.ts` + `src/store/<x>.ts` per section, static content in `src/data/*` as dead-API fallback, `Accept-Language: en`).

## Already used (done, do not redo)

`restaurants`(+show), `cafes`(+show), `events`(+show), `event-categories`, `entertainment-activities`(+show), `accommodations`(+show), `cities`.

## Not used yet

| Group | Endpoints | Filters / params (from controllers) | Website target |
| --- | --- | --- | --- |
| Home | `GET home` | none (counts: cities, places, events, experiences, tour_guides, travel_deals) | Hero/About stats |
| Home | `GET destinations`(+`{placeId}`) | `city_id, q, per_page` | Home destination rail, destination detail |
| Experiences | `GET experiences`(+`{id}`) | `city_id, tour_guide_id` | Home + `/life-and-fun/experiences` |
| Guides | `GET tour-guides`(+`{id}`) | `city_id, q` | `/explore/tour-guides` |
| Culture | `GET cultural-venues`(+show) | `city_id, q` | History & Heritage, Arts & Culture |
| Areas | `GET neighborhoods`(+show) | `city_id, q` | `/explore/neighborhoods` |
| CMS | `GET cms/sections`, `cms/country-facts`, `cms/historical-events` | `page_key, group_key` | About Syria + timeline |
| Map | `GET map/pois` | **required** `north,south,east,west`; `types` (csv), `limit` ≤300 | `/explore/map` |
| Nearby | `GET nearby` | **required** `lat,lng`; `radius_km` 0.1-200, `per_page` ≤50 | `/services/nearest-destinations` |
| Deals | `GET travel-deals`(+`{id}`) | `city_id, deal_type_id` | `/deals/*` |
| Services | `GET embassies`, `airports`, `transport-providers` (+show each) | `city_id, q` | `/services/embassies`, `/services/transport` |
| Services | `GET important-numbers`(+show) | `city_id, category` | `/services` numbers list |
| Services | `GET faqs`(+show) | `scope` | FAQ accordion |
| Medical | `GET medical/destinations`, `medical/centers`(+show), `medical/specialties` | `city_id` | `/services/medical-tourism` |
| Invest | `GET investment/sectors`, **`POST investment/requests`** | body: `name, email, message` required; `phone, sector_id` | `/services/invest` form |
| Climate | `GET climate/seasons`, `climate/weather-tips`, `climate/forecast` | tips: `season_id`; forecast: **required** `city_id` (503 if weather provider down) | `/services/calendar` + weather widget |
| Videos | `GET videos`(+`{id}`) | `city_id, q` | Home/Explore video strip |
| Celebrations | `GET celebration-venues`(+show) | `city_id, venue_style, q` | Events hub (weddings/venues) |
| Organizers | `GET event-organizers`(+show) | `kind, q` | Event detail organizer block |
| Places | `GET places`(+`{id}`) | `city_id, q, type, per_page` | Global search; generic detail |
| Cities | `GET cities/{city}` | none | City page (Explore) |
| Assistant | `POST assistant/chat` | `message` 2-1000, `locale` ar/en | Chat panel |
| Auth | `register, login, verify-email, resend-verification, forgot-password, verify-reset-code, reset-password, google, google/redirect, google/callback`; authed: `me, PUT profile, logout` | register: `first_name,last_name,email,password(+_confirmation)`; verify: `email, code(6)`; reset: `reset_request_token`/`reset_token` | Account pages |
| Favorites | `GET favorites`, `POST favorites/toggle` (authed) | toggle: `reviewable_id` | Save buttons on cards |
| Reviews | `GET reviews`, `POST reviews` (authed) | `reviewable_id`; post adds `rating 1-5, comment` (needs approval) | Detail pages |

Frontend pages missing for linked nav routes: `/explore/{map,tour-guides,history-and-heritage,arts-and-culture,neighborhoods}`, `/life-and-fun/entertainment`, `/deals/*`, `/services/*`.

## Preflight (before Section A)

- Port 8000 currently answers `{"status":false,"message":"Resource not found."}` for every `/api/v1/*` route, so the Laravel backend is not the process running there (its envelope uses `success`). Start it: `cd ../backend && php artisan serve` (seed with `php artisan migrate --seed`), confirm `GET /api/v1/home` returns `{success:true}`.
- Probe the real response shape of each new endpoint with curl before typing it (`Accept-Language: en`), and record gaps in "Backend notes" at the bottom.
- Backend edits need your OK first.

## Working rule for every section

1. API module + types, zustand store (reuse `createListStore` / `createDetailStore`), UI wired, static fallback kept.
2. `npx tsc --noEmit`.
3. **Test in Claude in Chrome** (1440 and 390 widths): data renders from the API, filters work, empty state, dead-API fallback (point `NEXT_PUBLIC_API_URL` at a dead port), no console errors, no horizontal scroll.
4. **Stop. Report with screenshots and wait for your review.** The next section starts only after you approve.

## Sections (in order)

### A. Home data (DONE, reviewed)
`home`, `destinations`, `experiences`, `travel-deals` (preview). Hero/About stats from `home`; destination rail and experiences cards from the API; reuse `useHomeEvents/Food/Stays` pattern in `src/store/home.ts`.
Test: home at 1440/390, cards link to detail routes, fallback to `src/data/home.ts`.

### B. Tour Guides + guided experiences (DONE, reviewed)
`experiences` (list/detail, wire the existing `/life-and-fun/experiences` and `details/experience`), new `/explore/tour-guides` from `tour-guides` with city filter and search.
Test: filter by city, guide to experiences link via `tour_guide_id`.

### C. Explore content (DONE, reviewed)
`cms/sections` + `cms/country-facts` + `cms/historical-events` into `/explore/about-syria` (replaces `src/data/explore.ts`); new pages `history-and-heritage` and `arts-and-culture` from `cultural-venues`; `neighborhoods`; `cities/{city}` for a city header.
Test: About Syria shows CMS text and timeline, venue lists filter by city, detail pages open.

### D. Interactive map + Nearby (DONE, reviewed)
`map/pois` (bounds from the map viewport, `types` filter chips, debounce on pan; pick a map lib, ask you first) and `nearby` (browser geolocation, `radius_km`) for `/services/nearest-destinations`.
Test: markers render, pan refetches, geolocation denied state, empty state.

### E. Deals (DONE, reviewed)
`travel-deals` list (filters `city_id`, `deal_type_id`) and detail under `/deals/accommodation-and-entertainment`. Violet accent only here (design system).
Test: list, filter, detail, fallback.

### F. Services directories (DONE, reviewed)
`embassies`, `airports`, `transport-providers`, `important-numbers`, `faqs` (accordion). Shared directory component, city filter and search.
Test: each page lists and filters; FAQ accordion keyboard operable.

### G. Medical tourism + Invest in Syria (DONE, reviewed)
`medical/destinations|centers|specialties` with specialty filter; `investment/sectors` + `POST investment/requests` form with inline validation errors (422 `errors` map) and success state.
Test: submit form on the local backend only; validation and success states.

### H. Climate / Syrian Calendar (DONE, reviewed)
`climate/seasons`, `weather-tips` (by season), `forecast` (city picker; handle 503 "weather unavailable" gracefully).
Test: season switch, forecast, 503 state (simulate by dead city/offline).

### I. Videos, celebrations, organizers (DONE, reviewed)
`videos` strip on Home/Explore, `celebration-venues` (venue_style filter) on the Events hub, `event-organizers` block on event detail.
Test: each renders and falls back cleanly.

### J. Accounts, favorites, reviews (built, awaiting review)
Auth store (token already handled by `client.ts`), pages: login, register + `verify-email` code step, forgot/verify/reset, profile (`me`, `PUT profile`), logout; Google sign-in (`auth/google`, needs your Google client id). Save buttons call `favorites/toggle` and redirect logged-out users to login; `/account/favorites` from `favorites`; review list + form on detail pages (new review shows "pending approval").
Test: full register-verify-login-logout, favorite persists after reload, review pending. Tokens never logged; use the local demo account only.

### K. Assistant + global search
`assistant/chat` chat panel (send site `locale`, loading and error states). Search box uses `places?q=` (optionally `type`) with a results page.
Test: send/receive, error state, search results link to the right detail pages.

## Backend notes (fill in during preflight)

- `GET places` mixes all types; list items return `type: null` unless `type=` is passed. Use `type` to get the subtype.
- `forecast` depends on an external weather provider (Open-Meteo); a 503 shows a retry notice on `/services/calendar`. `climate/seasons` already embeds each season's `weather_tips`, so the site does not call `climate/weather-tips`.
- `medical/centers` has no specialty filter; the site fetches up to 100 and filters by specialty and city on the client. `medical/destinations` ignores `q` and has no show route; details use `places/{id}`.
- `investment/sectors` fact titles contain em-dashes; the site swaps them for colons on display.
- Open question: should map/nearby also respond with detail links? Confirm what `pois` items contain once the backend is running.