# Os dois caminhos

Tem dois jeitos de construir com a Fayz SDK, e escolher o certo no começo economiza retrabalho. Ou você usa o **App Fayz** — um shell de admin completo montado a partir da sua config — ou vai de **Fayz Headless**, consumindo o core e os bundles de plugin direto no seu próprio projeto. Os dois usam os mesmos plugins e o mesmo backend; muda **quem é dono da casca** em volta dos plugins.

Regra de bolso: se o produto **é** o app de gestão (um SaaS multi-tenant, um admin), vá de App Fayz. Se você já tem um site próprio — uma landing page, uma loja com marca forte — e só quer plugar algumas capacidades dentro dele, vá de Headless.

## App Fayz

Você declara a config do app — em `app.manifest.json` ou em código com `defineSaas` — liga um conjunto de plugins, e ganha um app pronto: shell de admin, navegação gerada a partir dos plugins, troca de tenant, permissões e telas de CRUD. É o caminho mais rápido para um produto multi-tenant completo, e é o que o `fayz create admin` gera para você.

```ts
import { defineSaas } from '@fayz-ai/saas'
import { createAgendaPlugin } from '@fayz-ai/plugin-agenda'
import { createCrmPlugin } from '@fayz-ai/plugin-crm'

export default defineSaas({
  name: 'Minha Clínica',
  plugins: [createAgendaPlugin(), createCrmPlugin()],
})
// → shell de admin completo: navegação, tenants, permissões, CRUD
```

Você entra pelo [Quickstart](/pt-BR/docs/quickstart), que gera exatamente esse tipo de app e o sobe em modo mock. Consumindo os pacotes em código, os providers mock nascem vazios — [Mock e dados de exemplo](/pt-BR/docs/apps/mock-e-dados-de-exemplo) mostra como semeá-los.

## Fayz Headless {% badge status="beta" %}

Você importa `@fayz-ai/core` e monta as superfícies você mesmo, injetando os bundles de plugin (`{ manifest, Provider }`) e servindo os subpaths deles em `/public`. É o caminho para um site sob medida — marketing, loja, portal — que só quer algumas capacidades do Fayz sem adotar o shell inteiro. O tema herda dos seus próprios tokens, então o plugin se parece com o seu site, não com o admin padrão.

{% callout type="warn" %}
O caminho Headless é real e está em uso, mas tem **menos documentação** que o App Fayz hoje. Espere se apoiar mais na leitura dos tipos e dos exemplos, e menos em guias passo a passo, enquanto ele amadurece.
{% /callout %}

## Comparação

| | **App Fayz** | **Fayz Headless** |
|---|---|---|
| Quem monta o shell | a SDK (pronto) | você, no seu projeto |
| Navegação / rotas | geradas do manifesto | você conecta as suas |
| Multi-tenant + permissões | incluídos | você integra o que precisar |
| Tema | shell e tokens do Fayz | herda dos seus próprios tokens |
| Ponto de partida | `fayz create admin` | um site seu já existente |
| Melhor para | SaaS / admin de gestão | site com marca própria + algumas capacidades |
| Custo de entrada | mínimo — roda em minutos | maior — você é dono da integração |
| Documentação hoje | completa | em amadurecimento |

O que você ganha no App Fayz — shell, navegação, tenancy — é exatamente o que você abre mão de controlar. O Headless inverte: você controla tudo, e paga isso montando a integração. Nenhum é "melhor"; depende de o produto ser o app de gestão ou um site que consome capacidades.

## Escolha o seu

{% cards %}
{% card title="Caminho A · App Fayz" href="/pt-BR/docs/quickstart" icon="🏗️" %}
Comece pelo Quickstart: um shell de admin completo rodando em minutos.
{% /card %}
{% card title="Caminho B · Headless" href="/pt-BR/docs/apps/headless" icon="🧱" %}
Core + bundles de plugin dentro do seu próprio site.
{% /card %}
{% /cards %}