---
description: SeaHaven Admin — arquitetura IrisLoan, convenções de rebuild seletivo
alwaysApply: true
---

# SeaHaven Admin — convenções IrisLoan

## Stack

- Vite SPA + React Router 7, TypeScript strict, Tailwind v4 + MUI
- HTTP: Ky com `credentials: "include"` (cookies httpOnly)
- Server state: TanStack Query; forms: React Hook Form + Zod
- **Não usar** em código novo: Next.js, Redux, axios, `apiUtil.js`, `tokenUtility.js`

## Estrutura alvo (`src/`)

```
api/  domain/<feature>/  app/  infra/query-key/  lib/  hooks/
components/ui|common|layout/  config/menu.ts  providers/  main.tsx
```

- Alias `@/` para imports; arquivos novos em **kebab-case** (`use-debounce.ts`, `query-key.ts`)
- `pages/` é **somente referência** de endpoints e regras de negócio — deletar após entrega em `domain/` + `app/`

## HTTP e auth

- Centralizar paths em `api/api-paths.ts` e respostas em `api/handle-api-response.ts`
- Auth via AuthProvider + cookies; não criar slices Redux para sessão

## Estado e dados

- Cache e mutations: React Query + `infra/query-key/query-key.ts`
- Defaults do client em `lib/query/query-client.ts`

## Forms e UI

- Schemas Zod em `domain/<feature>/schemas/`; views finas em `app/`
- Tailwind utilitário + componentes MUI; **não** importar `site.css` em código novo

## Fluxo ao implementar feature

1. Consultar legado em `pages/<feature>/` (endpoints, campos, regras)
2. Criar `domain/<feature>/` (schemas, hooks, use-cases)
3. View fina em `app/` + rota em `app/routes.tsx`
4. Deletar `pages/<feature>/` quando a feature nova estiver pronta

## Tooling

- ESLint strict só em `.ts/.tsx` da arquitetura nova; legado em `pages/` ignorado
- Commits: Conventional Commits (`feat(scope): subject`)

Referência: `docs/ARCHITECTURE_PLAN.md`