# Arquitetura recomendada

Um roteiro para começar um projeto com o `@rivocode/ui` e fazê-lo crescer sem
virar uma pasta de componentes soltos. Não é molde obrigatório: é a organização
que a casa recomenda, e cada projeto adapta o que precisar. A pilha não entra na
recomendação: roteador, camada de dados e gerenciador de pacote são escolha do
projeto, e a biblioteca funciona com qualquer um.

O roteiro vale para os dois jeitos de montar a aplicação:

| Base | Quando usar |
| --- | --- |
| **Vite**, com o roteador que você preferir | sistema logado, que roda no navegador: painel, gestão, área do cliente |
| **Next.js** com App Router | quando a página precisa de SEO ou de servidor: site público, loja, página aberta |

Os formulários vêm do `@rivocode/ui/form`. Nos exemplos, os dados vêm do
TanStack Query, mas qualquer camada que entregue `data`, `isLoading` e `isError`
serve. Autenticação fica de fora: cada projeto liga a sua.

## Começar pelo comando

```bash
npm config set @rivocode:registry https://npm.pkg.github.com
npx -p @rivocode/ui rivocode-ui create
```

A primeira linha vai uma vez por máquina: sem ela o `npx` procura o pacote no
npmjs.com e responde 404. O token vem junto, como está na
[instalação](/instalacao).

Ele pergunta a base (Vite, Next ou Expo), o roteador, no Vite (TanStack Router,
React Router ou nenhum), e o gerenciador de pacote (npm, pnpm, yarn ou bun), e
entrega o projeto já com o `.npmrc`, o Tailwind, o CSS da biblioteca, o
Provider e a casca abaixo. Depois pergunta o resto desta página, com sim de
padrão: a camada de dados (`--dados`, o TanStack Query, com o
`QueryClientProvider` já montado como na casca abaixo), o formulário
(`--formulario`, o `react-hook-form`, o `zod` e o `@hookform/resolvers`) e a
skill com o MCP (`--skill`), para o agente abrir o projeto sabendo a
biblioteca. Quem usa outra camada de dados responde `nao`. O passo a passo à
mão está na [Instalação](/instalacao).

## As pastas: uma por funcionalidade

```
src/
  app/                 a casca: rotas, providers, AppShell
  features/
    pedidos/
      schema.ts        o Zod, que é a fonte do tipo
      api.ts           as chamadas ao servidor
      queries.ts       os hooks do TanStack Query
      pedidos-page.tsx a tela
      order-form.tsx   o formulário
      schema.test.ts   o teste
    painel/
  shared/              o que mais de uma funcionalidade usa
```

Funcionalidade nova é uma pasta nova em `features/`, e tudo dela mora ali: o
schema, a API, a tela e o teste. **Uma funcionalidade não importa de dentro da
outra**: o que as duas precisam sobe para `shared/`. É o que deixa apagar,
mover ou entregar uma funcionalidade sem caçar referência pelo projeto, e o que
faz o projeto de trinta telas ter a mesma cara do de três.

`app/` só monta: rota, provider e casca. Regra de negócio não mora lá.

## O que instalar

O `@rivocode/ui` mora no GitHub Packages: antes, o `.npmrc` do escopo
`@rivocode`, como na [Instalação](/instalacao).

```bash
npm install @rivocode/ui lucide-react @tanstack/react-query react-hook-form zod @hookform/resolvers
npm install -D tailwindcss
```

No Vite, mais o roteador escolhido e o `@tailwindcss/vite`. No Next, mais
`@tailwindcss/postcss`. O CSS e o plugin do Tailwind seguem a
[Instalação](/instalacao).

## A casca

O `RivoProvider` fica uma vez só, por fora de tudo, e o `AppShell` monta o
cabeçalho, a barra lateral e o conteúdo. O item da barra lateral recebe o link
do router pelo `render`: sem ele, cada clique recarrega a página inteira.

No Vite, o `RouterProvider` é o do roteador escolhido:

```tsx
// src/main.tsx
createRoot(document.getElementById('root')!).render(
  <RivoProvider theme="system">
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </RivoProvider>,
)
```

A casca, aqui com o React Router. No TanStack Router muda só a importação, e o
caminho atual vem do `useRouterState`, como em [Roteador e dados](/roteador-e-dados):

```tsx
// src/app/shell.tsx
import { Link as RouterLink, Outlet, useLocation } from 'react-router'

export function Shell() {
  const { pathname } = useLocation()

  return (
    <AppShell
      container
      sidebar={
        <SidebarContent>
          <SidebarMenu>
            <SidebarMenuItem render={<RouterLink to="/pedidos" />} active={pathname === '/pedidos'}>
              Pedidos
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarContent>
      }
    >
      <Outlet />
    </AppShell>
  )
}
```

Cada tela entra na rota por import dinâmico, e só é baixada quando alguém a
abre: o `lazy` no React Router, o `lazyRouteComponent` no TanStack Router. Os
dois estão em [Roteador e dados](/roteador-e-dados).

No Next, os providers vão num arquivo de cliente, e a casca usa o `Link` de
`next/link` e o `usePathname`:

```tsx
// src/app/providers.tsx
'use client'

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())

  return (
    <RivoProvider theme="system">
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </RivoProvider>
  )
}
```

```tsx
// src/app/shell.tsx
'use client'

<SidebarMenuItem render={<Link href="/pedidos" />} active={pathname === '/pedidos'}>
  Pedidos
</SidebarMenuItem>
```

O `layout.tsx` da raiz embrulha tudo em `<Providers><Shell>{children}</Shell></Providers>`,
e cada `page.tsx` só renderiza a tela da funcionalidade.

## Uma funcionalidade inteira

**O schema é a fonte da verdade.** Ele valida o formulário e dá o tipo, e o
campo brasileiro leva o validador da biblioteca:

```ts
// src/features/pedidos/schema.ts
export const orderSchema = z.object({
  customer: z.string().trim().min(2, 'Informe o nome do cliente'),
  document: z.string().refine(isValidCpf, 'CPF inválido: confira os dígitos'),
  amount: z.number().int().positive('O valor precisa ser maior que zero'),
})
```

**A consulta mora num hook**, e a tela não sabe de onde o dado vem:

```ts
// src/features/pedidos/queries.ts
export function useOrders() {
  return useQuery({ queryKey: ['pedidos'], queryFn: listOrders })
}

export function useCreateOrder() {
  const client = useQueryClient()
  return useMutation({
    mutationFn: createOrder,
    onSuccess: () => client.invalidateQueries({ queryKey: ['pedidos'] }),
  })
}
```

**A tela desenha os quatro finais**, e não só o caminho feliz:

```tsx
<DataTable
  data={orders.data}
  isLoading={orders.isLoading}
  isError={orders.isError}
  onRetry={() => orders.refetch()}
  rowKey={(row) => row.id}
  columns={columns}
  empty={{
    title: 'Nenhum pedido por aqui',
    description: 'Quando a loja vender pela primeira vez, o pedido aparece nesta lista.',
    action: <Button onClick={() => setCreating(true)}>Registrar o primeiro pedido</Button>,
  }}
/>
```

**O formulário usa a peça certa para cada dado**: máscara e validador no CPF,
centavos inteiros no dinheiro.

```tsx
<Form form={form} onSubmit={onSubmit}>
  <FormField name="customer" label="Cliente">
    {(field) => <Input {...field} autoComplete="name" />}
  </FormField>
  <FormField name="document" label="CPF do cliente">
    {(field) => <MaskedInput {...forValue(field)} mask="cpf" />}
  </FormField>
  <FormField name="amount" label="Valor">
    {(field) => <CurrencyInput {...forValue(field)} />}
  </FormField>
  <Button type="submit" loading={form.formState.isSubmitting}>
    Registrar pedido
  </Button>
</Form>
```

**Excluir oferece desfazer**, em vez de pedir confirmação:

```tsx
const { mutateAsync: removeOrder } = useMutation({ mutationFn: deleteOrder })
const { mutate: undoRemove } = useMutation({ mutationFn: restoreOrder })

async function removeWithUndo(order: Order) {
  await removeOrder(order.id)
  const id = toast.add({
    title: `Pedido ${order.number} excluído`,
    timeout: 8000,
    actionProps: {
      children: 'Desfazer',
      onClick: () => {
        undoRemove(order)
        toast.close(id)
      },
    },
  })
}
```

Criar e editar abrem numa `Sheet` ao lado da lista, que mantém o contexto de
trás. O motivo de cada uma dessas escolhas está no guia de fluxo da
[Skill](/skill).

## O agente trabalhando do jeito da casa

Três arquivos na raiz do projeto fazem o Claude Code, o Cursor ou outro agente
seguir este roteiro sozinho:

- **A skill**, com `npx rivocode-ui skill` (e `--para codex`, `copilot`,
  `gemini`, `cursor` ou `todos` fora do Claude Code): o contrato da biblioteca,
  a escolha de peça e as regras de fluxo.
- **O MCP**, em `.mcp.json` no Claude Code (cada ferramenta tem o seu arquivo,
  listado em [Para agents](/para-agents)):

```json
{
  "mcpServers": {
    "rivocode-ui": {
      "command": "npx",
      "args": ["-y", "@rivocode/ui-mcp"],
      "env": { "RIVOCODE_NPM_TOKEN": "${RIVOCODE_NPM_TOKEN}" }
    }
  }
}
```

O pacote é privado: o `.npmrc` do projeto, o mesmo da instalação, manda o
escopo `@rivocode` para o GitHub Packages, e basta no Claude Code, que sobe o
servidor na pasta do projeto. Os outros casos estão em [Para agents](/para-agents). O
`${RIVOCODE_NPM_TOKEN}` lê a variável do seu ambiente, e o token não entra no
repositório junto com o `.mcp.json`.

- **Um `CLAUDE.md`**, ou um `AGENTS.md` para as outras ferramentas, que diga a arquitetura: onde mora cada coisa, que
  funcionalidade não importa de outra, e as regras de interface (a peça do
  catálogo antes do `<div>`, o campo que sai do dado, os quatro finais e o
  desfazer). A auditoria de tela do MCP, o `audit_screen`, dá nota a uma tela
  pronta.

## Testes e CI

Um teste por funcionalidade, começando pelo schema, que é onde mora a regra:

```ts
test('recusa o CPF com dígito errado', () => {
  const result = orderSchema.safeParse({
    customer: 'Marina Souza',
    document: '123.456.789-00',
    amount: 128_000,
  })

  expect(result.success).toBe(false)
})
```

E a CI roda tipos, testes e build em todo push, para a `main` nunca receber o
que não compila.
