---
feature: Joshen guided search
slug: joshan
surface: client
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [CUST-009]
business_rules: [BR-02, BR-08, BR-09]
decisions: [DEC-02, TD-06, TD-12, TD-19, TD-22, TD-42, TD-78, TD-79, TD-80, TD-114, TD-115, TD-116, TD-117, TD-118, TD-119, TD-120]
schema_tables: [categories, services, service_occasions, occasions, packages, package_occasions, finder_searches, orders]
screens: [customer--search--*, customer--joshen-finder--*]
related_docs: [catalog.md, provider-selection.md, booking.md, orders.md, ../API_CONVENTIONS.md]
last_updated: 2026-11-09
---

# Joshen guided search — Flutter Integration Guide (client)

> **Base URL:** `{HOST}/api/v1/client` · Shared request, response and error rules: [API_CONVENTIONS](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-11-09 | PATCH | Docs only: the finder form and results screens (`customer--joshen-finder--01/02`) are mapped to this guide (they existed in the prototype index but in no registry row). | None. |
| 1.0.0 | 2026-10-26 | Initial | Adds the public guided-search config and paginated guided-search endpoints, including guest searches and normal order handoff. | Build the config-first flow, preserve the guest device id, and send `finder_search_id` when booking from a result. |

## Changelog

### 1.0.1 — 2026-11-09

- **Fixed (docs):** `screens` now lists `customer--joshen-finder--*` (form pages 1–2, results pages 1–3).
- **Breaking:** No. **App action required:** None.


### 1.0.0 — 2026-10-26
- **Added:** `GET /joshan/config` and `POST /joshan/search`; guest and customer searches use existing eligible services/packages and persist one search record for all pages.
- **Changed:** Orders from these results use `source=joshen_finder` and the search UUID.
- **Fixed:** N/A.
- **Removed / Deprecated:** No admin-handled special request exists (DEC-02).
- **Breaking:** No.
- **Endpoints affected:** `GET /joshan/config`, `POST /joshan/search`, `POST /orders`.
- **App action required:** Read config before showing Joshen; use the returned fields/lists/brackets; retain `X-Guest-Device-ID` for guest continuation and sign-in handoff.
- **BRD / decisions:** CUST-009, AC-CUST-009, BR-02/08/09, DEC-02, SCR-11, TD-114…120.

---

## 1. Business summary

Joshen helps a customer find an existing enabled service or package using service type, occasion, location, date/time, and optional budget. Eligibility and provider coverage are checked before featured ranking; featured providers never bypass a match. A zero-result search is a normal 200 response with an empty list. The booking journey stays the regular order flow.

## 2. User flow and screens

| Step | Screen / widget | Endpoint | Notes |
|------|-----------------|----------|-------|
| 1 | Joshen entry and form | `GET /joshan/config` | Hide the entry if `enabled=false`; render only `input_fields=true`. The app should still require a location because address cannot be hidden. |
| 2 | Guided criteria | Same | Use returned active category/package types, active occasions, and budget bracket values. A category UUID is a `service_type`; `package` is the literal package value. |
| 3 | Results | `POST /joshan/search` | Send location and visible inputs. No date/time means eligibility only; date plus optional time checks scheduled availability. |
| 4 | More results | `POST /joshan/search` | Send only `finder_search_id`, `page` (2+), and optional `per_page`; this continues the same log row. |
| 5 | Book a result | `POST /orders` | Send the ordinary booking payload with `source: joshen_finder` and the returned `finder_search_id`. |

## 3. Endpoints

### 3.1 Read finder configuration

`GET /api/v1/client/joshan/config` · route `client.joshan.config`

| | |
|---|---|
| Auth | Guest or customer token; the token is optional. |
| Extra headers | `Accept-Language`; `X-Guest-Device-ID` is needed for guest search, not config. |
| Rate limit | None. |

Response includes `enabled`, translated `name`/`description`, field visibility, `package_enabled`, `service_types`, active `occasions`, and configured `budget_brackets`. Lists use `{value,label}`. **Real response:** Postman `client.joshan.config` → “200 Public Joshen configuration while disabled”.

### 3.2 Search and continue results

`POST /api/v1/client/joshan/search` · route `client.joshan.search`

| | |
|---|---|
| Auth | Guest or customer token. |
| Extra headers | Guests must send a stable opaque `X-Guest-Device-ID` (max 100 characters). |
| Rate limit | Configured per user/device and per IP; 429 `RATE_LIMITED`. |

First-page JSON keys:

| Field | Type | Required | Meaning |
|-------|------|----------|---------|
| `service_type` | UUID string or `package` | When displayed | Active category UUID or package selector. |
| `occasion_id` | UUID string | No | Active occasion. |
| `address_id` | UUID string | One location | The signed-in customer's own saved address. |
| `city_id` | UUID string | With `district_id` | Active city (`governorates`); guests use city/district. |
| `district_id` | UUID string | One location | Active district (`regions`) within `city_id`. |
| `date` | `YYYY-MM-DD` | No | Desired local Saudi date; checks any scheduled slot on that date. |
| `time` | `HH:mm` | No | Scheduled slot time; requires `date`. |
| `budget_bracket` | string | No | `key` from config; exact configured boundaries. |
| `page` | integer | No | First call is page 1 (default); continuation uses 2 or higher. |
| `per_page` | integer | No | 1–100, default 15. |

For continuation, send `finder_search_id` (the response UUID), `page`, and optionally `per_page`; first-page criteria are prohibited. Every page returns the same `search_id` and total `results_count`.

**No matches — real 200 response** (Postman `client.joshan.search` → “Guest search with no matching offers”):

```json
{
  "status": "success",
  "message": "لم نعثر على خدمات مطابقة. يمكنك تعديل خيارات البحث.",
  "data": {
    "search_id": "01a17882-4c8f-718a-9bde-9b2ef3822fb3",
    "results_count": 0,
    "results": [],
    "pagination": {"page": 1, "per_page": 15, "last_page": 1}
  }
}
```

Every result has a typed `type`, UUID `id`, localized name, category/provider, exact two-decimal `price`, and duration. Service price is the provider's base price; optional-choice prices are excluded. Package price is the package price. Budget bounds use the first bracket as inclusive from `0.00`; later lower bounds are exclusive and upper bounds inclusive. `no_limit` does not filter by price.

**Errors:**

| HTTP | `error_code` | Meaning |
|------|--------------|---------|
| 422 | `JOSHEN_DISABLED` | Finder is disabled. |
| 422 | `JOSHEN_CONFIG_UNAVAILABLE` | Required settings are missing or invalid. |
| 422 | `JOSHEN_INPUT_DISABLED` | Request contains an input the admin hid. |
| 422 | `SERVICE_AREA_UNAVAILABLE` | Selected location is not serviceable. |
| 422 | validation | Time without date, invalid fields, or missing location. |
| 422 | `VALIDATION_FAILED` | Guest request omitted `X-Guest-Device-ID`. |
| 429 | `RATE_LIMITED` | Device/user or IP limit reached. **Real response:** Postman `client.joshan.search` → “Search rate limit exceeded”. |

The disabled-search response is captured at Postman `client.joshan.search` → “Search while Joshen is disabled”.

## 4. Enums and result fields

| Field | Values / shape | Meaning |
|-------|----------------|---------|
| `service_types[]` | `{value: category uuid, label}` or `{value: "package", label}` | Derived from active categories and the admin package switch. |
| `occasions[]` | `{value: uuid, label}` | Active occasions only. |
| `results[]` | `type: {value,label}` | `service` or `package`. |

## Data model

| Table | Read / write | Notes |
|-------|-------------|-------|
| `finder_searches` | Write once on first page; read on continuation | Stores criteria and total result count, including zero. Guest rows use `guest_device_id`; customer rows use `customer_id`. |
| `service_occasions`, `package_occasions`, `occasions` | Read | Association links have no public UUID (TD-22). |
| `orders` | Write through regular booking | Finder origin plus `finder_search_id`. |

## 5. Dart model sketch

```dart
class FinderPage {
  final String searchId;
  final int resultsCount; // total matching records, not this page's length
  final List<FinderResult> results;
  final int page;
  final int perPage;
}

class FinderResult {
  final String id; // uuid (TD-19)
  final EnumValue type;
  final String name;
  final String price; // exact money string
  final int durationMin;
}
```

## 6. Business rules enforced by the backend

| Rule | Backend behavior | Customer state |
|------|------------------|----------------|
| BR-02 | Guests may search; continuation is tied to the same guest device unless claimed during sign-in booking. | Keep a stable device id. |
| BR-08 | Only covered providers and selected eligible locations match. | Let the customer change location if no providers cover it. |
| BR-09 | Featured order is applied only after eligibility. | Do not treat featured status as a match or booking rule. |
| DEC-02 | No match is an empty list; no special request is created. | Offer a way to change inputs. |
| TD-117 | Date/time checks use the existing booking slot engine; packages use ordinary eligibility only. | A date-only search means any available scheduled slot that day. |

## 7. Notifications and real-time events

None are sent by finder search. Order notifications continue through the normal booking lifecycle.

## 8. Localization and UI notes

- Arabic is required for admin copy and occasion names; English is optional with Arabic fallback (TD-12).
- Money values are strings. Format them as SAR without converting the transport value to a float.
- Show the normal empty state when `results_count=0`; the response remains HTTP 200.
- CUST-005 home does not currently list Joshen; show the entry only where the app owns the finder entry point.

## 9. Integration checklist

- [ ] Fetch config before rendering the finder and honor `enabled` and `input_fields`.
- [ ] Use the exact configured bracket keys and labels.
- [ ] Keep `X-Guest-Device-ID` stable across search pages and sign-in booking handoff.
- [ ] Continue pages with `finder_search_id`; never treat `results_count` as current-page length.
- [ ] Send `source=joshen_finder` and `finder_search_id` when booking a result.
- [ ] Handle empty results, disabled inputs, 422 errors, and 429.

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-CUST-009 | Guest or customer searches existing services/packages using filters. | Only eligible results are returned and search is logged once. |
| AC-CUST-009 | No eligible match. | HTTP 200, empty results and total zero; no special request. |
| AC-CUST-009 | Continue a later page. | Same search UUID and total; no additional search log. |
| AC-CUST-009 | Book from a result. | Ordinary order flow records finder source and search UUID. |

## 11. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| TD-114 | Customer-facing product copy | Seed copy is neutral Arabic text, marked `product_copy_pending`; product must replace it. |
| TD-119 | Abuse limits | Defaults are configurable in `config/joshan_limits.php`. |
