# Technical Analysis — <PROJECT NAME>  (TEMPLATE)

> Copy to `docs/project/analysis.md` and fill at project start. Produced by [`../build/build-schema.md`](../build/build-schema.md).
> **Design-led:** you MUST read the **whole Figma file, screen by screen** — not the brief/PDF alone.
> Read the analysis **PDF visually** (extract diagrams/tables/screenshots — ERD, pricing, statuses — not just text;
> drop only styling). Figma = source of truth for screens; the PDF complements with rules/numbers/business.
> Field/type names in English; domain content in Arabic. Mark anything unknown `<?>` — never invent.

## 1) Overview
- App idea / value · primary users/roles · platforms · revenue model · integrations.
- **Audiences / apps (ONE project, split into apps sharing one backend+DB):** list each app = `<audience>` (+ platforms), e.g. `user` (app+web), `provider` (panel), `delegate` (app), `company` (app). Same audience across platforms (app+web) = the **same** feature set (one API). Not separate projects.
- **Auth model per audience (BLOCKER — decide here):** distinct entities (provider ≠ customer) → **default: a model + Sanctum guard per audience (multi-auth, like `admins`)**; same account type differing only in capabilities → one `users` + `user_type` + abilities. See [`../build/build-auth-audience.md`](../build/build-auth-audience.md).
- **Guest mode?** browse-only (just navigates to home — no backend) **or** action-capable (guest can add to cart/favorites → anchor to a device id `mac_address`, 14-char alphanumeric, merged on login). Decide from the screens.

## 2) Features (high level)
1. `<feature>` — `<one line>`

## 3) Screens map (FROM FIGMA — one row per screen; state the total count)
> Walk every screen. If the count is far below what the project implies, you haven't finished.
> - **Same-named screens get separate rows.** Dump each and diff; note what differs (state/variant/role) — never merge by name.
> - **List EVERY action per screen** (each maps to its own endpoint). One screen ≠ one API.
> - **Multi-step flows: map every step.** A task spanning several screens in sequence (e.g. change-phone: verify **current** → enter **new** → verify **new**) = one endpoint per step; never collapse it (credential changes use `OtpType::OLD_*/NEW_*`).
> - **Record the on-screen success/error copy** per action — it becomes the API message (ar+en), not a generic string.

| # | Audience / platform | Screen (Figma) | Fields / inputs / lists | Actions / states (one per line) | Entity / API (per action) |
|---|---------------------|----------------|--------------------------|----------------------------------|----------------------------|
| 1 | `<user / app>` | `<screen>` | `<...>` | `<accept / reject / …>` | `<endpoint per action>` |

**Total screens analyzed:** `<N>` (across all designs/audiences). Same audience/different platform (app+web) → don't double-count features; note the platform.

## 4) Entities — classify EACH as REUSE / ALTER / NEW
> REUSE = already in base (use as external reference). ALTER = existing table + new columns. NEW = create.
> Review existing base first: `database/schema/*.json` + `app/Models`.

| Entity | Class (REUSE/ALTER/NEW) | Key fields (+ Laravel type) | Translatable | Files/Images | Relations | Soft-delete | Enums (values) |
|--------|--------------------------|------------------------------|--------------|--------------|-----------|-------------|----------------|
| `<Foo>` | NEW | `<...>` | `<...>` | `<media: documents,images / *_files / none>` | `<belongsTo Bar>` | `<yes/no>` | `<Status: a,b>` |
| `users` | ALTER | `<+ national_id, ...>` | — | — | — | — | — |
| `media` | REUSE | (Spatie) | — | — | — | — | — |

## 5) Files & media decision
- Per file/image field: **Spatie `media`** (collections on the model) [default] OR dedicated `<entity>_files` table. State the choice + why.

## 6) APIs needed — grouped by AUDIENCE → flow (→ each becomes `api/<audience>/<flow>/<endpoint>.md`)
> Group endpoints by **audience** (the app) first, then flow → a folder per audience, then per flow, one
> self-contained file per API. `shared/` for cross-app endpoints. A single screen usually produces **several**
> endpoints — one per action/state-transition (accept, reject, …). List them all; don't stop at the "load" call.
> Same audience across app+web → **one** endpoint set, not duplicated.

**Audience `<user>` → Flow `<flow>`:**
- `<METHOD /api/v1/...>` — purpose — data (entity) — screen — action/state-transition.

## 7) Dashboard CRUDs needed (→ each becomes `cruds/<entity>.md`)
- `<Entity>` — features: soft-delete / status toggle / export / statistics / translations.

## 8) Real seed data (Arabic, realistic — for factories/seeders)
- `<Entity>`: `<realistic sample rows from the actual domain>`

## 9) Open questions (`<?>`) — BLOCKER
- `<unresolved item>` — **ALL must be resolved before the schema GATE.** Never gate or build on an open `<?>`.

## 10) Dependency-ordered backlog & sprints
> Order by dependency, not convenience: **foundations first** (auth/identity, shared lookups like geo/settings,
> media) → **core domain** (what the app is about) → **cross-cutting** (notifications, payments, exports, dashboards).
> A sprint may not run before the sprints it depends on are DONE (passed verify.md DoD).

| Sprint | Includes (APIs / CRUDs) | Depends on |
|--------|--------------------------|-----------|
| 1 | `<foundation APIs/CRUDs>` | — |
| 2 | `<core domain>` | Sprint 1 |
| 3 | `<cross-cutting>` | Sprint 2 |