# Senior Backend Assessment — مناسبات / Munasabat (design → current implementation)

> **Method:** Figma (`NKtB4qVpa3saHmQlrQunXu`) read screen‑by‑screen (93 screens) = source of truth; compared against the **actual codebase** (not any analysis file). Three clients must be consistent: **User App · Provider App · Admin Panel** + the API as the single source of truth for business rules.
> **Rules note:** `.ai/.cursorrules` and `rules/shared.md` referenced in the brief **do not exist** in this repo → conventions followed are `CLAUDE.md` + `docs/build/*` (thin controller → Form Request → Service → Resource/response trait; Form Requests for all validation; Policies/ownership server‑side; versioned `/api/v1`; Sanctum; Astrotomic translations; Spatie media; shared response traits).
> **Headline:** only the **base scaffold** exists. The entire **marketplace domain is unbuilt**. So most items below are ❌ Missing by construction — this is a *greenfield build on a solid base*, not a broken implementation to repair. The schema + analysis drafted in `docs/project/` are the foundation.

Legend: ✅ done · ⚠️ partial · ❌ missing · 🔴 incorrect · 🔐 security/authz · 🔗 cross‑system gap · 🗄️ DB/model · 🧠 business logic · 📡 API.

---

## 0) What already exists (reusable foundation) — ✅

| Area | Status | Files |
|---|---|---|
| **API auth (user)** — login (password), login‑code (OTP), request‑code (throttled), forgot‑password (request/verify/reset), logout, me (+`complete.info`) | ✅ reuse | `routes/api/v1/auth.php` · `app/Http/Controllers/Api/V1/Auth/*` · `Services/Auth/*` |
| **API profile** — change‑password; change‑phone & change‑email as **4‑step OTP** (request‑current → verify‑current → set‑new → verify‑new) | ✅ reuse — **matches the design's Change‑Mobile 4‑step flow exactly** | `routes/api/v1/profile.php` · `Api/V1/Profile/*` · `OtpType OLD_*/NEW_*` |
| **API lookups** — countries/regions/cities (+limited/by‑parent) | ✅ reuse for addresses & provider location | `routes/api/v1/{countries,regions,cities}.php` |
| **API notifications / settings (public+admin)** | ✅ reuse | `routes/api/v1/{notifications,settings}.php` |
| **Admin CRUDs** — users, complaints, contact‑messages, geography, pages, sliders, socials, roles/permissions, notifications, settings, landing content, home | ✅ reuse / extend | `app/Http/Controllers/Admin/*` |
| **Response envelope, media (Spatie), translations (Astrotomic), OTP service, RBAC, landing, schema‑designer, kanban** | ✅ reuse | `app/Traits/*`, base services |
| **Landing site** rebranded to Munasabat (colors/content/logo) | ✅ done this session | `public/landing/css/landing.css`, `lang/{ar,en}/landing.php`, `public/landing/img/logo.svg` |

> **Guards:** `web`(session→users) exists; **no `provider` guard yet** (needed).

---

## 1) User App — design vs backend

| Flow (design) | Required API | Current | Verdict |
|---|---|---|---|
| Onboarding/Register/Login/OTP/Terms | register, login, verify, resend, forgot(3) | auth exists; **register (name/email/phone/password+terms) + verify‑OTP on register** not wired to the app's register screen | ⚠️ (auth base present, register endpoint + flow to confirm) |
| Guest browse‑only + sign‑in gate | public catalog endpoints; protected actions 401→"برجاء تسجيل الدخول اولا" | — | ❌ 📡 |
| Home (greeting, banner/slider, occasions, categories, featured providers) | `GET /home`, `GET /sliders` | — | ❌ 📡 |
| Explore / Categories / Listing (filter+sort+paginate) | `GET /service-categories`, `GET /occasions`, `GET /providers?category_id&occasion_id&city&rating&price_range&available_date&sort` | — | ❌ 📡🧠 (sort: relevance/rating/price_asc/price_desc) |
| Search + suggestions + recent | `GET /search`, `/search/suggestions`, `/search/recent` (list/add/clear) | — | ❌ 📡 |
| Provider (Hall) details — 4 tabs | `GET /providers/{id}` (+services/packages/works/reviews/stats/availability) | — | ❌ 📡🗄️ |
| Favorites (toggle) | `GET/POST/DELETE /favorites` | — | ❌ 📡🔐 (own list only) |
| Addresses (CRUD + map + default) | `GET/POST/PUT/DELETE /addresses` | — | ❌ 📡🔐 |
| Booking 5‑step → create | `GET availability/time-slots`; `POST /bookings` (service|package, date, slot, location_type, address, payment_method) | — | ❌ 📡🧠🔐 (transaction + slot‑conflict + price calc) |
| My Bookings (upcoming/completed) + details + timeline | `GET /bookings?scope`, `GET /bookings/{id}` | — | ❌ 📡🔐 |
| Cancel booking (implied by FAQ, no screen) | `POST /bookings/{id}/cancel` | — | ❌ 🧠 (state‑machine) |
| Rate experience (completed only, 1 per booking) | `POST /bookings/{id}/review` | — | ❌ 📡🧠 (only own completed booking; unique) |
| Payment cards (list/add/delete, tokenized) | `GET/POST/DELETE /payment-cards` | — | ❌ 📡🔐 (no PAN/CVV storage) |
| Profile (edit, change‑password, change‑phone 4‑step, notifications toggle, language, delete account) | profile.* | change‑password/phone ✅; **edit‑profile, notifications toggle, language(locale), delete‑account** missing | ⚠️ |
| FAQs / Terms / Privacy / Contact | `GET /faqs`, `GET /pages/{slug}`, `POST /contact-messages` | base exists (admin side); **public read endpoints** to confirm | ⚠️ |
| Notifications (8 types, read/read‑all/unread‑count) | notifications.* | base notifications exist; **8 domain event types + senders** missing | ⚠️ |

---

## 2) Provider App — design vs backend  🔗 (brief REQUIRES this; Figma only designed provider AUTH)

> **Design gap:** Figma contains the provider **onboarding/auth only** (node 87:26925 + a duplicated auth cluster). **No provider operational screens** (manage services/packages/works/availability, received bookings, stats) are designed. The brief explicitly requires the Provider App to be complete → these are built **from domain logic** and must be confirmed.

| Capability | Required API (provider guard) | Current | Verdict |
|---|---|---|---|
| Provider registration + **documents** (سجل تجاري/رخصة) | `POST /provider/auth/register` (+ media documents) | — | ❌ 📡🗄️ |
| Admin approval gate (pending→approved/rejected/suspended) | status enforced before login/visibility | — | ❌ 🧠🔐 |
| Provider login/verify/forgot/logout/me | provider auth flow (separate Sanctum guard) | — | ❌ 📡🔐 |
| Manage **services** (CRUD + toggle) | `/provider/services/*` | — | ❌ 📡🔐 (own only) |
| Manage **packages** (+items) | `/provider/packages/*` | — | ❌ 📡🔐 |
| Manage **works/portfolio** | `/provider/works/*` | — | ❌ 📡🔐 |
| Manage **availability / time‑slots** | `/provider/availability/*` | — | ❌ 📡🧠 |
| **Received bookings** + state transitions (confirm/start/complete/reject) | `/provider/bookings/*` | — | ❌ 📡🧠🔐 (only own bookings; valid transitions) |
| Reviews received | `/provider/reviews` | — | ❌ 📡 |
| Provider dashboard stats | `/provider/dashboard` | — | ❌ 📡 |
| **IDOR protection** — provider cannot read/modify another provider's services/packages/works/bookings | ownership scope from token on every provider endpoint | — | ❌ 🔐 (must enforce server‑side) |

---

## 3) API / Backend (source of truth) — 🧠🔐📡

- ❌ 🗄️ **Domain schema unbuilt** — 18 new tables designed (`database/schema/catalog.json`, `bookings.json`): providers, service_categories(+trans), occasions(+trans), occasion_provider, services, packages, package_items, works, provider_time_slots, favorites, addresses, bookings, transactions, payment_cards, reviews, recent_searches. ALTER: `users+locale`; `settings` rows (commission/vat/currency/auto‑confirm).
- ❌ 🧠 **Booking state machine** — `pending→confirmed→in_progress→completed` (+`cancelled`); `payment_status unpaid→paid→refunded`. Invalid transitions must be rejected server‑side (State pattern). Timeline (created→paid→confirmed→in_progress→completed) derived from status + timestamps.
- ❌ 🧠 **Pricing/transaction** — `subtotal + vat(15%) + commission(%)` computed server‑side from settings (never trust client totals). `POST /bookings` wrapped in a **DB transaction**: create booking → charge via PaymentGateway → create `transactions` row → set status; on payment failure booking is **not** confirmed (per Terms copy). Booking ref `IHF‑YYYY‑####`, payment ref `PAY‑YYYY‑#####`.
- ❌ 🧠 **Slot conflict / double‑booking** — a provider time‑slot can't be booked twice (lock/unique check inside the transaction).
- ❌ 🔐 **Ownership/authz everywhere** — addresses, cards, favorites, bookings scoped to `auth()->id()`; provider resources scoped to provider id; review only by the booking's owner and only when `completed`; unique review per booking.
- ❌ 🔐 **Provider approval** — unapproved provider is hidden from catalog and cannot receive bookings.
- ⚠️ 📡 **Public vs protected** — catalog is public (guest browse); mutations require the right guard; 401 copy "برجاء تسجيل الدخول اولا".
- ❌ **Observer** — recompute `providers.rating_avg`/`rating_count` on review create/visibility change; recompute `providers.price_from` on service change.
- ❌ **Events/Jobs** — 8 notification types (DB + FCM) fired on booking/review transitions (exact ar copy captured in `analysis.md §8`).

---

## 4) Admin Panel — must support both apps

| Admin capability | Current | Verdict |
|---|---|---|
| Providers management + **approve/reject/verify/suspend** + view documents + stats | — | ❌ 🔗 |
| Service categories (translatable + icon) | — | ❌ |
| Occasions (translatable + image) | — | ❌ |
| Services / packages oversight | — | ❌ |
| Bookings oversight (filter/status/refund) | — | ❌ 🔗 |
| Reviews moderation (hide/delete) | — | ❌ |
| Transactions + financial/performance reports | — | ❌ |
| Settings: **commission %, vat %, currency, auto‑confirm** | base settings exist; **these rows** missing | ⚠️ |
| Sliders (home banners), FAQs, pages, contact, complaints, users, geography, notifications | ✅ base CRUDs reusable | ✅ |
| Dashboard home (KPIs) + reports pages | base home exists; domain KPIs | ⚠️ |

---

## 5) Cross‑system consistency — 🔗
Required end‑to‑end chain is **not wired** (nothing of the domain exists yet):
`Admin configures categories/occasions/approves provider → API exposes → User browses & books → Provider receives & transitions status → User sees updated status & rates → Admin monitors/reports.`
Each hop is a ❌ until the domain is built. The schema + plans are designed so every hop is covered.

---

## 6) Open blockers before building the domain
- 🧠 **A. Provider monetization / "Subscription":** the brief lists a **Subscription** entity, but **no subscription/plan screens exist in the Figma** and the user design only shows **per‑booking commission**. Need to confirm: do providers pay a **subscription/plan to be listed/featured** (⇒ new `plans` + `subscriptions` tables + gating), or is monetization **commission‑only** (current design)? If subscriptions are in scope, is there a separate provider/subscription design?
- 🔗 **B. Provider operational screens undesigned** — will be built from domain logic (full provider API, per the brief). Confirm the field set for provider service/package/availability management is acceptable as designed in `analysis.md`.
- ⚙️ **C. Payment gateway** (Moyasar/HyperPay/Tap) + default **commission %** — gateway abstracted behind a `PaymentGateway` strategy; need the provider + default rate.
- 🗝️ **D. Environment** — `.env` is **absent** (`.env.example` points at shared DB `base2025`). A clean project DB + `APP_KEY` + `TELESCOPE_ENABLED=false` are required before migrations/seed/`schema:check`.
- 🎨 **E. Logo/favicon** assets not provided (temporary wordmark in place).

---

## 7) Recommended build order (dependency‑first; each sprint = full three‑app slice, server‑side rules enforced)
1. **Foundations** — provider guard+model, `users+locale`, settings rows, service_categories + occasions (tables + admin CRUD + seed).
2. **Provider catalog** — providers (admin CRUD + approval + documents) · services · packages(+items) · works · time‑slots · provider auth API.
3. **User browse** — user register/verify wiring · home · catalog list/details · search(+recent) · favorites.
4. **Booking & payment** — addresses · payment‑cards · bookings (create+transaction+pricing+slot‑lock) · details/timeline · cancel · reviews (+rating observer).
5. **Provider bookings** — received bookings + state transitions · provider reviews · provider dashboard.
6. **Admin & cross‑cutting** — bookings/reviews/transactions admin + reports · dashboard KPIs · 8 notifications (DB+FCM) · public faqs/pages/contact.

> Full entity/field/endpoint detail: `docs/project/analysis.md`. Schema: `database/schema/{catalog,bookings}.json` (+`features.json`).

---

## 8) Admin dashboard coverage review (design → admin CRUDs)
> Can the admin configure/manage everything the User & Provider apps need?

**✅ Covered** (built Sprints 1–2 or reusable base): servicecategories · occasions · providers (approve/reject/suspend/verify/feature/block + documents + gallery + stats) · services + packages (oversight) · users · sliders (home banner) · pages (terms/privacy) · socials · settings (commission `app_commission` + VAT `vat_ratio` via pricing tab) · roles/permissions · complaints · contactmessages · notifications (send) · geography · landing-content editor.

**❌ Gaps (being built):**
- `bookings` oversight (list/filter by status·provider·date, show + timeline + financial breakdown, refund/cancel with valid-transition guards).
- `reviews` moderation (list, toggle is_visible, delete, recompute provider rating).
- `transactions` (financial list/filter) + `reports` (revenue · commission · VAT · bookings-by-status · top providers/categories).
- `faqs` admin CRUD — base ships Faq model+seeder but **no admin CRUD** though the app shows FAQs.
- dashboard-home **domain KPIs** (users/providers/pending-approval/bookings-by-status/revenue/top categories).
- settings: add `currency` + `booking_auto_confirm` fields to the pricing tab.

**⚠️ Optional:** works oversight (provider-owned) · Export columns for new entities · seo/intro admin (base).