---
feature: Home page and intro slides
slug: home
surface: client
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [CUST-005, CUST-001]
business_rules: [BR-02, BR-08, BR-09, BR-30]
decisions: [D1, DEC-23, TD-15, TD-19, TD-36, TD-64, TD-69, TD-78, TD-79, TD-80]
schema_tables: [sliders, slider_translations, onboarding_slides, onboarding_slide_translations, categories, category_translations, services, provider_services, provider_categories, providers, provider_districts, packages, package_items, wallets, customer_addresses, v_provider_featured]
screens: [customer--home--*, customer--onboarding--*]
related_docs: [catalog.md, addresses.md, auth.md, ../admin/banners.md, ../admin/content.md]
last_updated: 2026-10-26
---

# Home page and intro slides — Flutter Integration Guide (client)

> **Base URL:** `{HOST}/api/v1/client` · Shared rules (headers, envelope,
> errors, pagination, Dio setup): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Version history

Newest first. Never edit an old row.

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-10-26 | PATCH | Documentation only: validation 422 examples and rows now show `data.errors` (`{field: [messages]}`, TD-02, API_CONVENTIONS 2.7.0) instead of `data: null`; examples are the captured Postman responses. | None. |
| 1.0.0 | 2026-10-22 | Initial | Intro slides and the home page (banners, categories, packages, header), public with an optional customer token. Base `GET /client/sliders` retired. | Integrate as described below; stop calling `/client/sliders`. |

## Changelog

### 1.0.1 — 2026-10-26

- **Added:** N/A.
- **Changed:** Validation 422 examples and error-table rows show `data.errors`, not `data: null` (TD-02).
- **Fixed:** Documentation only; the server already returned `data.errors`.
- **Removed / Deprecated:** N/A.
- **Breaking:** No.
- **Endpoints affected:** None (documentation).
- **App action required:** None; map `data.errors` onto form fields, fall back to `message`.
- **BRD / decisions:** TD-02.

### 1.0.0 — 2026-10-22
- **Added:** `GET /onboarding-slides`, `GET /home` (public; optional customer token).
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** base `GET /client/sliders` is unregistered (404); use `home.banners` (TD-80).
- **Breaking:** No (the base route was never part of a released feature doc).
- **Endpoints affected:** `GET /onboarding-slides`, `GET /home`, `GET /sliders` (removed)
- **App action required:** build the intro and home screens from these endpoints; send the customer token when signed in.
- **BRD / decisions:** CUST-001, CUST-005, SCR-08, SCR-09, BR-02/08/09/30, TD-78/79/80.

---

## 1. Business summary

Anyone can open the app and browse without an account (CUST-001, BR-02). The
intro slides come from the admin's `onboarding_slides`. The home page shows the
admin's banners for the customer app, the main service categories, and provider
packages available at the customer's service location. A signed-in customer
also gets a header block: greeting name, wallet balance, and the address the
page was filtered by.

The **same URL** serves guests and signed-in customers. With a customer token,
the page uses her default address (or the `address_id` she picks); a guest may
send `city_id` / `district_id`. Packages only appear when their provider is
eligible at that location (BR-08); featured providers rank first, but only after
that filter (BR-09).

## 2. User flow and screens

| Step | Screen / widget | Endpoint | Notes (states, empty, loading, errors) |
|------|-----------------|----------|-----------------------------------------|
| 1 | Intro slides (`customer--onboarding--0[1-3]`) | `GET /onboarding-slides` | Empty list → skip the intro. "Skip" and "Replay intro" are app-side. |
| 2 | Home, guest (`customer--home--01`) | `GET /home` (no token) | `user` is `null` → show the guest card with "Log in". Booking actions open login (BR-02). |
| 3 | Home, signed in (`customer--home--02`) | `GET /home` (token) | Header from `user`: name, `wallet_balance`, `address.formatted`. "Change" opens the address picker (`GET /addresses`), then reload with `address_id`. |
| 4 | Banners carousel | `home.banners` | Tap follows `link_type` / `link` (§4). Hide the carousel when empty. |
| 5 | Categories grid (`customer--home--03`) | `home.categories` | "N services" = `services_count`. Tap → category page ([catalog.md](catalog.md)). "View all" → `GET /categories`. |
| 6 | Packages strip | `home.featured_packages` | Up to 10. Empty until providers publish packages (PROV-011) — hide the section when empty. "View all" → `GET /search?type=packages`. |
| 7 | Active order strip (`customer--home--04`) | `home.active_order` | Always `null` until the orders feature ships; hide the strip. |
| — | Group-booking card | — | Static entry point; group booking is `client/booking.md`. |
| — | Search bar | — | Opens search ([catalog.md](catalog.md) §3.4). |

```
Intro slides ──► Home ──► Category ──► Service details ──► (login) ──► provider selection (CUST-010)
                   └──► Search / Packages
```

## 3. Endpoints

### 3.1 Intro slides

`GET /api/v1/client/onboarding-slides`

| | |
|---|---|
| Auth | Public. Optional customer token (ignored for content; a bad token is 401). |
| Extra headers | `Accept-Language: ar` (default) or `en` |
| Rate limit | None |

**Query parameters:** none.

**Success — `200`**

```json
{
  "status": "success",
  "message": "Intro slides retrieved.",
  "data": [
    {
      "id": "01a16342-45ee-7086-a61a-cdea94a58ad6",
      "title": "Beauty comes home",
      "body": "Instant service within 45 minutes",
      "image": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
    },
    {
      "id": "01a16342-45e8-732f-8de0-972716fe2682",
      "title": "Your safety first",
      "body": "Verified specialists",
      "image": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
    }
  ]
}
```

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| `id` | uuid | no | Slide id |
| `title`, `body` | string | yes | Request locale, Arabic fallback |
| `image` | URL | no | Placeholder URL when no image is uploaded |

Only active slides of the customer app, ordered by the admin's `sort_order`. No slides → `"data": []`.

**Errors**

| HTTP | `error_code` | When | What the app should do |
|------|--------------|------|------------------------|
| 401 | `UNAUTHENTICATED` | A token was sent but is invalid or expired | Refresh the token (or drop it and continue as guest) |

### 3.2 Home page

`GET /api/v1/client/home`

| | |
|---|---|
| Auth | Public. Optional customer token: without one the request is a guest; a sent token must be a valid **customer** token. |
| Extra headers | `Accept-Language` |
| Caching | Signed-in responses are `Cache-Control: no-store, private` |

**Query parameters** (all optional; precedence `address_id` → `city_id`/`district_id` → default address, TD-78)

| Name | In | Type | Required | Rules | Description |
|------|----|------|----------|-------|-------------|
| `address_id` | query | uuid (string) | no | string, max 64; must be one of **her** live addresses | Signed-in only. Filter by this saved address instead of the default. |
| `city_id` | query | uuid (string) | with `district_id` | uuid, exists `governorates` | City to browse (guest, or a customer looking at another city). Must be enabled. |
| `district_id` | query | uuid (string) | no | uuid, exists `regions`; needs `city_id` | District of that city. Must belong to it and be enabled. |

**Success — `200`, guest**

```json
{
  "status": "success",
  "message": "Home retrieved.",
  "data": {
    "banners": [
      {
        "id": "01a16342-4615-71e2-a26f-581447857d8c",
        "title": "Sample-vpfw81703524",
        "subtitle": null,
        "badge_text": null,
        "image": "https://ui-avatars.com/api/?name=S&background=e0e7ff&color=4f46e5&size=400",
        "link_type": {
          "value": "none",
          "label": "No link"
        },
        "link": null
      },
      {
        "id": "01a16342-4610-7134-a63a-ba67f63b02ad",
        "title": "25% off the monthly care package",
        "subtitle": "View the package",
        "badge_text": "Offer of the week",
        "image": "https://ui-avatars.com/api/?name=S&background=e0e7ff&color=4f46e5&size=400",
        "link_type": {
          "value": "category",
          "label": "Category"
        },
        "link": "category-uuid"
      }
    ],
    "categories": [
      {
        "id": "01a16342-4622-739c-b874-3bf08f32834f",
        "name": "Makeup",
        "description": "Occasion makeup",
        "icon_key": "lipstick",
        "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
        "services_count": 1
      }
    ],
    "featured_packages": [],
    "user": null,
    "active_order": null
  }
}
```

**Success — `200`, signed in at her default address**

```json
{
  "status": "success",
  "message": "Home retrieved.",
  "data": {
    "banners": [],
    "categories": [
      {
        "id": "01a16342-4662-717f-82ec-99375cafdb62",
        "name": "Makeup",
        "description": "Occasion makeup",
        "icon_key": "lipstick",
        "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
        "services_count": 1
      }
    ],
    "featured_packages": [
      {
        "id": "01a16342-46e0-7176-82ba-f0011c5dca90",
        "name": "Full glam package",
        "description": null,
        "image": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200",
        "category": {
          "id": "01a16342-4662-717f-82ec-99375cafdb62",
          "name": "Makeup"
        },
        "provider": {
          "id": "01a16342-4669-707f-831e-14049fe0bf17",
          "name": "Jonatan Williamson"
        },
        "price": "640.00",
        "compare_at_price": "760.00",
        "savings_amount": "120.00",
        "validity_days": 60,
        "services": [
          {
            "id": "01a16342-4665-70ef-989e-667174e3dd4a",
            "name": "Evening makeup",
            "sessions": 2
          }
        ]
      }
    ],
    "user": {
      "name": "Roosevelt Pouros",
      "wallet_balance": "480.50",
      "address": {
        "id": "01a16342-46e9-7330-a6e1-e741d336fae8",
        "label": "Home",
        "label_type": {
          "value": "home",
          "label": "Home"
        },
        "city": {
          "id": "01a16342-4656-7069-b3c9-24c3883957c0",
          "name": "Riyadh"
        },
        "district": {
          "id": "01a16342-465d-70c8-b517-15ca937bd135",
          "name": "Al Yasmin"
        },
        "address_line": "Prince Sultan Street",
        "details": null,
        "lat": null,
        "lng": null,
        "is_default": true,
        "formatted": "Riyadh، Al Yasmin، Prince Sultan Street"
      },
      "is_service_area_available": true
    },
    "active_order": null
  }
}
```

**Success — `200`, default address in an area that was disabled later**

```json
{
  "status": "success",
  "message": "Home retrieved.",
  "data": {
    "banners": [],
    "categories": [
      {
        "id": "01a16382-aeb8-7344-8373-fcdd692b8034",
        "name": "Makeup",
        "description": "Occasion makeup",
        "icon_key": "lipstick",
        "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
        "services_count": 1
      }
    ],
    "featured_packages": [],
    "user": {
      "name": "Dr. Hayden Schoen",
      "wallet_balance": "0.00",
      "address": {
        "id": "01a16382-aef7-713e-8d22-d2195ee1a51c",
        "label": "Home",
        "label_type": {
          "value": "home",
          "label": "Home"
        },
        "city": {
          "id": "01a16382-aeae-7297-921b-812ec941ad7f",
          "name": "Riyadh"
        },
        "district": {
          "id": "01a16382-aeb3-73ac-ae75-a7b579447a56",
          "name": "Al Yasmin"
        },
        "address_line": "Prince Sultan Street",
        "details": null,
        "lat": null,
        "lng": null,
        "is_default": true,
        "formatted": "Riyadh، Al Yasmin، Prince Sultan Street"
      },
      "is_service_area_available": false
    },
    "active_order": null
  }
}
```

**Response fields**

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| `banners[]` | Banner | no (list) | Customer-app home banners: active, inside their display dates (BR-30). `title`, `subtitle`, `badge_text` localized; `image` URL; `link_type` EnumValue; `link` string or null. |
| `categories[]` | Category | no (list) | Active categories in admin order: `id`, `name`, `description`, `icon_key`, `image`, `services_count` (active bookable services). Same shape as `GET /categories`. |
| `featured_packages[]` | PackageCard | no (list) | Up to 10 live packages of providers eligible at the location; featured providers first, then newest. Same card as search ([catalog.md](catalog.md) §3.4). |
| `featured_packages[].savings_amount` | money string | yes | `compare_at_price − price`; null without a compare-at price |
| `user` | object | **yes** | `null` for a guest |
| `user.name` | string | no | Greeting name (`users.full_name`) |
| `user.wallet_balance` | money string | no | Refund credit balance (CUST-016); `"0.00"` without a wallet |
| `user.address` | Address | yes | The saved address the page was filtered by — same shape as [addresses.md](addresses.md). `null` when she has no address or browses with `city_id`. |
| `user.is_service_area_available` | bool | yes | `false` when that address's city/district was disabled after it was saved: show "service unavailable here, choose another address". `null` without a location. |
| `active_order` | object | yes | Always `null` until `client/orders.md` ships |

**Errors**

| HTTP | `error_code` | When | What the app should do |
|------|--------------|------|------------------------|
| 401 | `UNAUTHENTICATED` | Sent token invalid or expired | Refresh; on failure drop the token and continue as guest |
| 403 | `PERMISSION_DENIED` | Token of another app (provider/driver) | Use the customer token |
| 404 | `ENTITY_NOT_FOUND` | `address_id` is not one of her live addresses, or sent by a guest | Reload addresses and pick again |
| 422 | `SERVICE_AREA_UNAVAILABLE` | Chosen `address_id`, city or district is disabled | Show the message; ask for another area (AC-CUST-004) |
| 422 | `BUSINESS_RULE_VIOLATED` | `district_id` does not belong to `city_id` | Reset the district picker |
| 422 | — (`data.errors`) | Malformed uuid, `district_id` without `city_id` | Show the message under the field named in `data.errors` |

```json
{
  "status": "fail",
  "message": "Unauthenticated, you have to login first",
  "data": {
    "error_code": "UNAUTHENTICATED"
  }
}
```

```json
{
  "status": "fail",
  "message": "You do not have permission to access this app.",
  "data": {
    "error_code": "PERMISSION_DENIED",
    "correlation_id": "4794a7fc-fe54-4e2e-859b-d299af5cca25"
  }
}
```

```json
{
  "status": "fail",
  "message": "Address not found.",
  "data": {
    "error_code": "ENTITY_NOT_FOUND",
    "correlation_id": "6875f346-3c0b-4542-9b12-fc0d818aa24b"
  }
}
```

```json
{
  "status": "fail",
  "message": "Service is unavailable in this city or district. Please choose another service area.",
  "data": {
    "error_code": "SERVICE_AREA_UNAVAILABLE",
    "correlation_id": "0b6e1409-fbfe-41a0-83a7-a5c37a12514e"
  }
}
```

```json
{
  "status": "fail",
  "message": "The selected district does not belong to this city.",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "context": {
      "violations": [
        "The selected district does not belong to this city."
      ]
    },
    "correlation_id": "36d98009-e337-42aa-b4ce-dc3a03ddf34f"
  }
}
```

```json
{
  "status": "fail",
  "message": "The city id field must be a valid UUID.",
  "data": {
    "errors": {
      "city_id": [
        "The city id field must be a valid UUID."
      ]
    }
  }
}
```

## 4. Statuses and enums

| Enum | `value` | Meaning | App action on tap |
|------|---------|---------|-------------------|
| banner `link_type` | `none` | No link | Not tappable |
| | `category` | `link` = category uuid | Open category page |
| | `service` | `link` = service uuid | Open service details |
| | `package` | `link` = package uuid | Open package (when package details ship) |
| | `provider` | `link` = provider uuid | Open provider profile (CUST-010) |
| | `screen` | `link` = app screen key | App route table |
| | `url` | `link` = web URL | Open in browser |

The `link` value is what the admin saved (ADMIN-023, [admin/banners.md](../admin/banners.md)); the backend does not rewrite it.

## Data model

| Table (`db-schema.sql`) | Read / write | Notes |
|-------------------------|--------------|-------|
| `onboarding_slides` (+ translations) | read | `app = customer`, `is_active`, `sort_order` |
| `sliders` (+ `slider_translations`) | read | `target_app = customer`, `placement = home`, `is_active`, `starts_at`/`ends_at` (UTC) |
| `categories`, `services` | read | Active categories; count of active type-1 services |
| `packages`, `package_items` | read | `status = approved`, `is_visible`, not `hidden_by_admin` (= `v_live_packages`) |
| `providers`, `provider_districts`, `provider_categories`, `provider_services` | read | Eligibility (TD-78) |
| `v_provider_featured` | read | Ranking only |
| `wallets`, `customer_addresses` | read | Header block |

## 5. Dart models

```dart
class HomePage {
  final List<Banner> banners;
  final List<CategoryTile> categories;
  final List<PackageCard> featuredPackages; // catalog.md
  final HomeUser? user;                     // null = guest
  final Map<String, dynamic>? activeOrder;  // null until orders ship

  HomePage.fromJson(Map<String, dynamic> j)
      : banners = (j['banners'] as List).map((e) => Banner.fromJson(e)).toList(),
        categories = (j['categories'] as List).map((e) => CategoryTile.fromJson(e)).toList(),
        featuredPackages = (j['featured_packages'] as List).map((e) => PackageCard.fromJson(e)).toList(),
        user = j['user'] == null ? null : HomeUser.fromJson(j['user']),
        activeOrder = j['active_order'] as Map<String, dynamic>?;
}

class HomeUser {
  final String name;
  final String walletBalance;        // money string
  final Address? address;            // addresses.md model
  final bool? isServiceAreaAvailable;

  HomeUser.fromJson(Map<String, dynamic> j)
      : name = j['name'] as String,
        walletBalance = j['wallet_balance'] as String,
        address = j['address'] == null ? null : Address.fromJson(j['address']),
        isServiceAreaAvailable = j['is_service_area_available'] as bool?;
}

class Banner {
  final String id;
  final String? title, subtitle, badgeText, link;
  final String image;
  final EnumValue linkType;

  Banner.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        title = j['title'] as String?,
        subtitle = j['subtitle'] as String?,
        badgeText = j['badge_text'] as String?,
        image = j['image'] as String,
        linkType = EnumValue.fromJson(j['link_type']),
        link = j['link'] as String?;
}

class CategoryTile {
  final String id;
  final String? name, description, iconKey;
  final String image;
  final int servicesCount;

  CategoryTile.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        name = j['name'] as String?,
        description = j['description'] as String?,
        iconKey = j['icon_key'] as String?,
        image = j['image'] as String,
        servicesCount = j['services_count'] as int;
}

class OnboardingSlide {
  final String id;
  final String? title, body;
  final String image;

  OnboardingSlide.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        title = j['title'] as String?,
        body = j['body'] as String?,
        image = j['image'] as String;
}
```

## 6. Business rules enforced by the backend

| Rule | What the backend does | What the user sees |
|------|-----------------------|--------------------|
| BR-02 | Home and slides are public; no token = guest | Guest card; booking prompts login |
| BR-30 | Only active customer-app home banners inside their dates | Expired/future/other-app banners never appear |
| BR-08 | Packages only from providers that are approved, accepting bookings, active, covering the location and with a fully priced service (TD-78) | Packages change with the address |
| BR-09 | Featured providers' packages first, after the BR-08 filter | No "Featured" label (DEC-23 open) |
| TD-36 | Suspended providers are not eligible | Their packages disappear |
| TD-69 | `address_id` must be hers; chosen disabled areas are refused | 404 / 422 as in §3.2 |

## 7. Notifications and real-time events

N/A — the home page emits no notifications.

## 8. Localization and UI notes

- Banner, slide, category texts follow `Accept-Language`, falling back to Arabic.
- Package `name` / `description` are the provider's own text (not translated).
- Money strings are SAR with 2 decimals; format with the app's currency helper.
- `image` fields are always URLs (placeholders when nothing is uploaded).

## 9. Integration checklist

- [ ] Models parse the real responses above (guest `user: null`, signed-in block)
- [ ] Customer token sent when signed in; 401 → refresh, 403 → wrong token
- [ ] Address switcher reloads with `address_id`; 404/422 handled
- [ ] `is_service_area_available: false` shows the unavailable notice
- [ ] Empty banners / packages hide their sections; `active_order` strip hidden while `null`
- [ ] Banner taps routed by `link_type`
- [ ] Stopped calling `GET /client/sliders`
- [ ] Tested in `ar` (RTL) and `en`

## 10. Acceptance scenarios

| AC ID | Scenario | Expected | Test |
|-------|----------|----------|------|
| AC-CUST-005 | Open the home page | Configured banners, main services, provider packages, navigation into details | `HomeControllerTest::test_ac_cust_001_guest_home_shows_live_banners_categories_and_null_user`, `…test_ac_cust_005_signed_in_home_uses_default_address_wallet_and_address_id` |
| AC-CUST-005 | Featured order | Featured provider's package first, out-of-area/paused subscriber excluded | `…test_ac_cust_005_featured_packages_rank_only_after_eligibility` |
| AC-CUST-001 | Guest browses | Same URL without token; a bad/other-app token refused | `…test_ac_cust_001_optional_token_is_verified_when_sent`; booking login prompt is app-side until booking ships |
| AC-CUST-005 (SCR-08) | Intro slides | Customer-app active slides in order; none configured → `[]` | `…test_ac_cust_005_onboarding_slides_are_customer_app_only_in_order`, `…test_ac_cust_005_onboarding_slides_empty_when_none_configured` |
| AC-CUST-004 | Disabled area | Chosen disabled city or district 422; another customer's or a guest's `address_id` 404; default in disabled area loads with no packages | `…test_ac_cust_005_location_errors_are_typed`, `…test_ac_cust_005_default_address_in_disabled_area_shows_no_providers` |

## 11. Open decisions and known limitations

| ID | Impact on this feature | Current behavior |
|----|------------------------|------------------|
| DEC-23 | Customer-facing "Featured" label and home-page package highlighting | Not shown; featured status only changes the order |
| TD-78 / PROV-006 | `is_accepting_bookings` has no toggle yet | Real providers are not eligible until the provider home ships the toggle, so packages stay empty in real data |
| PROV-011 | Providers cannot create packages yet | `featured_packages` is `[]` in real data (key stays) |
| — | `active_order` | `null` until client/orders.md |
| — | Joshen finder card (CUST-009) | client/joshan.md |
