# BEEB BEEB — Client app screen cycle

Reference board: [`client-full-cycle.png`](./client-full-cycle.png)  
Register/onboarding detail: [`client- register flow.png`](./client-%20register%20flow.png)

**Postman:** Each API request docs include the matching Figma link — see `docs/postman/FIGMA.md` and `scripts/postman/figma-screens.php`.

---

## 1. Onboarding & auth

| # | Screen (Figma) | User action | API | Response highlights |
|---|----------------|-------------|-----|---------------------|
| 1 | Splash | Auto-advance | — | Local only |
| 2 | Intro carousel | Next / Login | `GET /api/client/app-intro` | Slides for carousel |
| 3 | Phone entry | Send OTP | `POST /api/client/login` | `key: needVerification` |
| 3b | Phone entry (new) | Register | `POST /api/client/register` | `key: needActive` |
| 4 | OTP (6 digits) | Confirm | `PUT /api/client/activate` or `POST /api/client/verify-login` | `ClientResource` + `token` |
| 5 | Complete profile + verify email | Name + photo, then email OTP | `POST /api/client/profile/complete`, `POST /api/client/email/verify` | `needs_profile_completion: false`, `can_start_ride` (when eligible) |

**Auth response shape** (`ClientResource`): `is_profile_completed`, `needs_profile_completion`, `in_ride`, `balance_low`, `can_start_ride`, `wallet.balance`, `token`.

---

## 2. Home & map

| # | Screen | User action | API | Response highlights |
|---|--------|-------------|-----|---------------------|
| 6 | Home / map | Open app | `GET /api/client/home` | Greeting, balance card, pricing, notification badge |
| 7 | Map markers | Pan/zoom | `GET /api/client/scooters/available?lat&lng` | Scooters with `code`, `battery_percent`, `distance_m`, `price_per_minute` |
| 8 | Scooter sheet (DIV-182) | Tap marker | `GET /api/client/scooters/{code}?lat&lng` | Model, battery bar, range, **Start ride** CTA |

---

## 3. Ride cycle

| # | Screen | User action | API | Response highlights |
|---|--------|-------------|-----|---------------------|
| 9 | QR scan / manual code | Scan SCT-XXXX | `POST /api/client/rides/scan` | `status: scanning`, scooter details |
| 10 | Unlock | Confirm start | `POST /api/client/rides/{id}/unlock` | `status: active`, timer starts |
| 11 | Active ride | Live timer | `GET /api/client/rides/active` | `elapsed_seconds`, `current_cost`, `remaining_balance`, scooter battery |
| 12 | End ride modal | End trip | `POST /api/client/rides/{id}/end` | Duration, distance, cost preview |
| 13 | Trip summary (DIV-123) | View receipt | `GET /api/client/rides/{id}` | Total cost, remaining balance |
| 14 | Parking photo | Upload proof | `POST /api/client/rides/{id}/parking-photo` | `status: completed` |
| 15 | Rate ride | 1–5 stars | `POST /api/client/rides/{id}/rate` | `rating` saved |

---

## 4. Wallet

| # | Screen | User action | API | Response highlights |
|---|--------|-------------|-----|---------------------|
| 17 | Wallet (85.50 SAR) | View balance | `GET /api/client/wallet` | `balance`, `total_spent`, `total_topped_up`, `quick_amounts` |
| 18 | Transactions | Scroll list | `GET /api/client/wallet/transactions` | Type, amount, sign, date/time |
| 19 | Top-up (DIV-356) | Pay | `POST /api/client/wallet/charge` | `redirect_url` / payment session |
| 20 | Packages tab | Browse | `GET /api/client/subscription-packages` | Day/week/month prices |
| 21 | Active package | View progress | `GET /api/client/subscription/active` | Expiry + progress bar |

---

## 5. My rides

| # | Screen | User action | API | Response highlights |
|---|--------|-------------|-----|---------------------|
| 22 | Stats card | — | `GET /api/client/rides/stats` | Spent, hours, km, count |
| 23 | Rides list | Filter month | `GET /api/client/rides?filter=this_month` | Status badge, cost, route |
| 24 | Ride detail sheet | Tap row | `GET /api/client/rides/{id}` | Full trip breakdown |

---

## 6. Account & support

| # | Screen | User action | API | Response highlights |
|---|--------|-------------|-----|---------------------|
| 25 | Account menu | Open | `GET /api/client/profile` | Name, phone, image, settings flags |
| 26 | Edit profile | Save | `POST /api/client/update/profile` | Updated `ClientResource` |
| 27 | Change phone | 2-step OTP | `POST send-code-to-old-phone` → `verify-new-phone` | — |
| 28 | Notifications toggle | Switch | `PATCH /api/client/switch-notify` | `notify` |
| 29 | Language | Arabic/English | `PATCH /api/client/change-lang` | — |
| 30 | Contact / support | Send message | `POST /api/client/contact` | — |
| 31 | Complaint + photos | Submit ticket | `POST /api/client/complains` | Ticket id |
| 32 | Delete account (DIV-137) | Confirm | `DELETE /api/client/delete-account` | Blocked if balance > 0 |
| 33 | Logout | Confirm | `POST /api/client/logout` | — |

Static (no auth): `GET /api/client/terms`, `privacy`, `about`, `socials`.

---

## Bottom navigation → API groups

| Tab | Primary endpoints |
|-----|-------------------|
| Home | `home`, `scooters/available`, ride flow |
| My Rides | `rides/stats`, `rides` |
| Wallet | `wallet`, `wallet/transactions`, `subscription-packages` |
| Account | `profile`, `switch-notify`, `change-lang`, `logout` |

---

## App routing hints (computed flags)

| Condition | Screen destination |
|-----------|-------------------|
| `needs_profile_completion` | Complete profile / verify email |
| `in_ride` | Active ride |
| `balance_low` | Wallet top-up |
| `is_blocked` | Support message |
| `can_start_ride` | Home map / scan |