shoc-frontend-new/docs/ARCHITECTURE_PLAN.md

# Architecture Plan — SeaHaven (Selective Rebuild)

> Aligned with IrisLoan.Admin · Vite SPA + React Router · **no Next.js** · Tailwind + MUI

Mirror document of the Cursor plan. Strategy: **reuse knowledge, discard legacy code** — do not normalize/refactor the current project.

---

## Strategy in one sentence

Build `api/` + `domain/` + `app/` from scratch; use `pages/` only as **endpoint and business rule reference**; **delete** each legacy folder when the new feature is ready.

---

## Matrix: Keep vs Discard

### Keep (extract logic → new code)

| Legacy                                | Keep                             | Destination                                      |
| ------------------------------------- | -------------------------------- | ------------------------------------------------ |
| `lib/api/services.js`                 | ASP.NET paths + response parsing | `api/api-paths.ts`, `api/handle-api-response.ts` |
| `pages/*/api.js`                      | Real endpoints                   | `api/api-paths.ts`                               |
| `constants/queryKeys.js`              | Entities                         | `infra/query-key/query-key.ts`                   |
| `hooks/useDebounce.js`, `useModal.js` | Hooks                            | `hooks/*.ts`                                     |
| `hooks/api/usePMSchedules.js`         | RQ pattern                       | Template `domain/*/use-cases/`                   |
| `lib/queryClient.js`                  | Cache defaults                   | `lib/query/query-client.ts`                      |
| `App.js`, `Sidebar.js`                | Routes and menu                  | `app/routes.tsx`, `config/menu.ts`               |
| `pages/workorders/` (list)            | Business flow                    | Reference for POC                                |

### Discard (delete without refactoring)

- `apiUtil.js`, `services/api.js`, `lib/api/client.js`
- `tokenUtility.js`, `authService.js`, Redux (`app/store.js`, slices)
- `usePaginatedList.js`, entire `pages/` folder (after replacement)
- `Site.Layout.js`, `setupProxy.js`, `site.css`, per-feature CSS, Font Awesome
- Forms `*FormPage.js` (rewrite with RHF + Zod)
- `SharedTable.js`, `ActionBar.js` (recreate if adapting is costly)

### Defer (later)

- `pages/vendor-portal/` → `domain/vendor-portal/`
- `pages/calendar/` → new FullCalendar wrapper

---

## Feature priority

Full matrix (waves, dependencies, LOC, done criteria): **[`FEATURE_PRIORITIZATION.md`](FEATURE_PRIORITIZATION.md)** · TS config: [`src/config/feature-priorities.ts`](../src/config/feature-priorities.ts).

| Wave              | Scope                                                                       |
| ----------------- | --------------------------------------------------------------------------- |
| **0 POC**         | auth → work-orders (list)                                                   |
| **1 must-have**   | work-orders (full), dashboard, settings/dropdowns                           |
| **2**             | 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            |

Stakeholder decision: **auth + work-orders first**; POC = auth + work-orders list (not pm-schedules).

---

## Target structure

```
src/
├── api/
├── domain/<feature>/
├── infra/query-key/
├── lib/
├── components/ui/ + common/
├── app/
├── config/menu.ts
├── hooks/
├── providers/
└── main.tsx
```

---

## Phases

| Phase | Goal                                                                                  |
| ----- | ------------------------------------------------------------------------------------- |
| **0** | Complete foundation (Ky, routes, layout, AuthProvider, tooling) — Vite/TS/Tailwind ok |
| **1** | Ky + httpOnly auth cookies; delete legacy HTTP stacks                                 |
| **2** | Rewrite must-have features; delete `pages/<feature>/` per delivery                    |
| **3** | UI shell + RHF+Zod forms                                                              |
| **4** | Remove `pages/`, Redux, legacy CSS; Docker + CI + Vitest                              |

---

## Next steps

1. Complete foundation (`api/api.ts`, `routes.tsx`, AuthProvider, layout shell)
2. `api/api-paths.ts` (extract from `lib/api/services.js`)
3. POC: `domain/auth` + login → delete `pages/auth/`
4. POC: `domain/work-orders` (list) → delete list portion of `pages/workorders/`
5. Cookie contract with backend

---

See full plan with diagrams in `.cursor/plans/migração_arquitetura_irisloan_cf39e1a6.plan.md`.