shoc-frontend-new/docs/FEATURE_PRIORITIZATION.md

# Feature Prioritization Matrix — Sea Haven

> Source of truth for legacy → `domain/` + `app/` migration order.
> Machine-readable config: [`src/config/feature-priorities.ts`](../src/config/feature-priorities.ts).

---

## Stakeholder decisions

| Decision                 | Detail                                                                                    |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| Top priority             | **`auth`** and **`work-orders`**                                                          |
| End-to-end POC           | **`auth` + work-orders (list)** — validate Ky, React Query, layout shell and AuthProvider |
| Other features           | Flexible order, guided by technical dependencies (waves below)                            |
| POC **does not** include | `pm-schedules` (deferred to Wave 4)                                                       |

---

## Full matrix

| Order | Feature                   | Tier        | Wave | Legacy folder                       | Routes                                                                        | LOC ~  | Dependencies                                                                 |
| ----- | ------------------------- | ----------- | ---- | ----------------------------------- | ----------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| 1     | auth                      | POC         | 0    | `pages/auth/`                       | `/login`                                                                      | 513    | —                                                                            |
| 2     | work-orders (list)        | POC         | 0    | `pages/workorders/` (list)          | `/workorders`                                                                 | 4.3k\* | auth                                                                         |
| 3     | work-orders (form + view) | must-have   | 1    | `pages/workorders/`                 | `/workorders/new`, `/workorders/:id`, `/workorders/edit/:id`                  | 4.3k\* | auth, work-orders (list), settings/dropdowns, accounts, locations, employees |
| 4     | dashboard                 | must-have   | 1    | `pages/Dashboard.js`                | `/`, `/dashboard`                                                             | 253    | auth                                                                         |
| 5     | settings/dropdowns        | must-have   | 1    | `pages/settings/` (DropdownOptions) | `/settings/dropdowns`                                                         | 866\*  | auth                                                                         |
| 6     | accounts                  | must-have   | 2    | `pages/accounts/`                   | `/accounts`, `/accounts/new`, `/accounts/edit/:id`                            | 745    | auth                                                                         |
| 7     | locations                 | must-have   | 2    | `pages/locations/`                  | `/locations` (Add Site modal, detail panel)                                   | 1.1k   | auth, accounts                                                               |
| 8     | employees                 | must-have   | 2    | `pages/employees/`                  | `/employees`, `/employees/new`, `/employees/edit/:id`                         | 1.9k   | auth                                                                         |
| 9     | vendors                   | should-have | 3    | `pages/vendors/`                    | `/vendors`, `/vendors/new`, `/vendors/edit/:id`                               | 610    | auth, work-orders (full)                                                     |
| 10    | vendor-pos                | should-have | 3    | `pages/vendor-pos/`                 | `/vendor-pos`, `/vendor-pos/:id`                                              | 1k     | auth, work-orders (full)                                                     |
| 11    | uplifts                   | should-have | 3    | `pages/uplifts/`                    | `/uplifts`                                                                    | 317    | auth, work-orders (full)                                                     |
| 12    | follow-ups                | should-have | 3    | `pages/followup/`                   | `/followups`, `/followups/new`, `/followups/edit/:id`                         | 1.3k   | auth, employees, accounts, locations                                         |
| 13    | contacts                  | should-have | 3    | `pages/contacts/`                   | `/contacts`, `/contacts/new`, `/contacts/edit/:id`                            | 1.1k   | auth                                                                         |
| 14    | settings/task-templates   | should-have | 3    | `pages/settings/` (TaskTemplates)   | `/settings/task-templates`                                                    | 866\*  | auth, work-orders (full)                                                     |
| 15    | calendar                  | later       | 4    | `pages/calendar/`                   | `/calendar`, `/calendar/new`, `/calendar/edit/:id`                            | 1.9k   | auth                                                                         |
| 16    | vendor-portal             | later       | 4    | `pages/vendor-portal/`              | `/v/:token`, `/v/:token/dashboard`, `/v/:token/pos`, `/v/:token/dispatch/:id` | 1.4k   | auth, vendors                                                                |
| 17    | pm-schedules              | later       | 4    | `pages/PmSchedule/`                 | `/pmschedules`, `/pmschedules/new`, `/pmschedules/edit/:id`                   | 1.1k   | auth                                                                         |
| 18    | assets                    | later       | 4    | `pages/assets/`                     | `/assets`, `/assets/new`, `/assets/edit/:id`                                  | 638    | auth, accounts                                                               |
| 19    | reports / documents       | later       | 4    | — (no implementation)               | `/reports`, `/documents` (menu only)                                          | —      | auth                                                                         |

\* LOC for the entire folder; POC scope uses only the list submodule.

### Legacy complexity (reference)

| Feature       | Complexity | Notes                                                     |
| ------------- | ---------- | --------------------------------------------------------- |
| auth          | Low        | Replace Redux/`tokenUtility` with AuthProvider + cookies  |
| dashboard     | Medium     | Real KPIs via `GET /Dashboard/Stats`                      |
| work-orders   | **High**   | Monolithic view; dispatch, checklist, signoff             |
| contacts      | High       | Legacy form **stub** (save TODO) — rewrite with RHF + Zod |
| employees     | High       | Large form                                                |
| vendor-portal | High       | URL token auth + signature                                |
| calendar      | High       | FullCalendar wrapper                                      |
| pm-schedules  | Medium     | Legacy API bugs (`PmSchedule/Create` vs `Save`)           |

---

## Dependency graph

```mermaid
flowchart TD
  subgraph wave0 [Wave0_POC]
    auth[auth]
    woList[work_orders_list]
  end
  subgraph wave1 [Wave1_MustHave]
    woFull[work_orders_full]
    dash[dashboard]
    dropdowns[settings_dropdowns]
  end
  subgraph wave2 [Wave2_Dependencies]
    accounts[accounts]
    locations[locations]
    employees[employees]
  end
  subgraph wave3 [Wave3_ShouldHave]
    vendors[vendors]
    vendorPos[vendor_pos]
    uplifts[uplifts]
    followups[follow_ups]
    contacts[contacts]
    settingsTpl[task_templates]
  end
  subgraph wave4 [Wave4_Later]
    calendar[calendar]
    vendorPortal[vendor_portal]
    pmSched[pm_schedules]
    assets[assets]
    reports[reports_documents]
  end
  auth --> woList
  woList --> woFull
  dropdowns --> woFull
  accounts --> woFull
  locations --> woFull
  employees --> woFull
  woFull --> vendors
  vendors --> vendorPortal
  woFull --> vendorPos
  woFull --> uplifts
```

### Waves (summary)

| Wave  | Tier        | Features                                                                    |
| ----- | ----------- | --------------------------------------------------------------------------- |
| **0** | POC         | auth, work-orders (list)                                                    |
| **1** | must-have   | work-orders (full), dashboard, settings/dropdowns                           |
| **2** | must-have   | accounts, locations, employees                                              |
| **3** | should-have | vendors, vendor-pos, uplifts, follow-ups, contacts, settings/task-templates |
| **4** | later       | calendar, vendor-portal, pm-schedules, assets, reports/documents            |

> `accounts` and `locations` can progress in parallel with the WO view if the list POC uses data already available in the backend; the order above is the minimum sequence for the full WO form.

---

## Legacy gaps and cleanup

| Item                     | Location                                                  | Migration action                                                                             |
| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Duplicate dashboard      | `pages/dashboard/` (mock prototype)                       | **Not routed** — ignore; use only `pages/Dashboard.js` as reference                          |
| Orphan login             | `pages/user/api.js`                                       | Delete in Phase 1 (Ky + auth); duplicates `pages/auth/` flow                                 |
| Ghost menu               | `Sidebar.js` → Reports `/reports`, Documents `/documents` | No routes or pages — implement from scratch (Wave 4) or remove from menu in `config/menu.ts` |
| Incomplete contacts form | `pages/contacts/form/`                                    | Do not port stub; rewrite with RHF + Zod in Wave 3                                           |
| PM schedules API         | `pages/PmSchedule/`                                       | Document Create vs Save inconsistency; fix in rewrite                                        |

---

## "Done" criteria per feature

A feature is **done** when all items below are met:

1. **`domain/<feature>/`** — Zod schemas, hooks/use-cases, types; no imports from `pages/`, Redux, axios or `apiUtil`
2. **`app/`** — thin views (list, form, view as scoped) registered in `app/routes.tsx`
3. **`api/api-paths.ts`** — feature endpoints centralized; responses via `handle-api-response.ts`
4. **`infra/query-key/query-key.ts`** — feature query keys
5. **Protected route** — navigation via `config/menu.ts` (when applicable to the wave)
6. **Delete legacy** — `pages/<feature>/` folder (or equivalent files) removed after validation
7. **No regression** — main flow tested manually or with Vitest (when available)

### Done criteria for special scope

| Scope                    | Additional criterion                                                               |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **POC auth**             | Login/logout with httpOnly cookies; `AuthProvider` replaces Redux + `tokenUtility` |
| **POC work-orders list** | Paginated/filtered list with Ky + RQ; no form/view in this delivery                |
| **work-orders full**     | Form + view (dispatch, checklist, signoff) functional                              |
| **settings/dropdowns**   | Problem/Trade/SubTrade dropdowns available for WO form                             |
| **reports/documents**    | Explicit decision: implement feature or remove menu links                          |

---

## References

- Architecture plan: [`ARCHITECTURE_PLAN.md`](ARCHITECTURE_PLAN.md)
- IrisLoan conventions: `.cursor/rules/seahaven-admin.mdc`
- Legacy routes: `src/App.js`
- Legacy menu: `src/components/Sidebar.js`