# Configuração

O `app.manifest.json` descreve o app inteiro num único arquivo JSON. Ele é a fonte da verdade: surfaces, tema, locale, backend e plugins. Esta página é o mapa de cada bloco de topo — o que ele faz e o que o `fayz doctor` valida.

## A forma do manifesto

Um app admin recém-criado se parece com isto (`manifestVersion` sempre `2` nesta geração):

```json
{
  "manifestVersion": 2,
  "id": "minha-loja",
  "name": "Minha Loja",
  "backend": { "provider": "mock" },
  "locale": { "default": "pt-BR", "supported": ["pt-BR", "en"], "currency": "BRL" },
  "theme": { "brand": "violet" },
  "surfaces": {
    "admin": {
      "scaffold": "admin",
      "plugins": [{ "id": "dashboard" }],
      "pages": []
    }
  }
}
```

Os quatro campos obrigatórios são `manifestVersion`, `id`, `name` e `surfaces`. O resto é opcional e tem default sensato.

## Os blocos de topo

| Campo | Papel |
| --- | --- |
| `id` | Identificador em kebab-case (`^[a-z0-9][a-z0-9-]*$`). |
| `name` | O nome exibido do app. |
| `backend` | De onde vêm os dados. Objeto `{ provider, ... }` — detalhado abaixo. |
| `locale` | Idioma, idiomas suportados e moeda. |
| `theme` | A marca: `brand`, `radius`, `mode` (veja [Temas](/pt-BR/docs/apps/temas)). |
| `permissions` | Declaração de features e ações (deny-by-default no multi-tenant). |
| `surfaces` | As faces do app. Pelo menos uma é obrigatória. |

## O bloco `backend`

O `provider` decide de onde os dados vêm. Os valores aceitos:

| `provider` | Para quê |
| --- | --- |
| `mock` | Dados de exemplo em memória, zero configuração. É o default do scaffold. Ao consumir os pacotes em código, os providers mock nascem vazios — veja [Mock e dados de exemplo](/pt-BR/docs/apps/mock-e-dados-de-exemplo) para semeá-los. |
| `supabase` | Um projeto Supabase real. Acompanha `projectRef`. |
| `fayz-api` | A API gerenciada do Fayz. |
| `fayz-shop` | O backend de e-commerce do Fayz. |
| `custom` | Um adapter próprio, referenciado por `adapterId`. |

Trocar de `mock` para `supabase` é o passo do meio do tutorial — veja [Supabase](/pt-BR/docs/dados/supabase):

```json
{ "backend": { "provider": "supabase", "projectRef": "seu-project-ref" } }
```

## Surfaces e plugins

Dentro de `surfaces`, cada surface declara o `scaffold` (obrigatório), uma lista de `plugins` e uma de `pages`. Ligar uma capacidade é adicionar `{ "id": "..." }` à lista `plugins` — os pacotes já vêm nas dependências do app gerado, então não há nada para instalar nem para editar em `src/plugins.generated.ts`. Cada `pluginRef` aceita `config` (opções do plugin) e `enabled` (para desligar sem remover).

Como as rotas e o menu são derivados dessa lista, o detalhe está em [Rotas e navegação](/pt-BR/docs/apps/rotas-e-navegacao).

## Duas formas de configurar

O scaffold entrega a forma **manifesto-primeiro**: você edita JSON e a plataforma renderiza. Existe também a forma **código-primeiro**, em que a configuração vive em `src/` (via `defineSaas` / `defineStorefront`). O `fayz doctor` reconhece as duas: um app sem `app.manifest.json` mas com `package.json` é tratado como app código-primeiro — o doctor roda as checagens de boundary e passa. Comece pela forma manifesto; ela cobre a maioria dos casos e é a que a plataforma edita ao vivo.

## Valide sempre

Depois de qualquer edição, rode o doctor. Ele confere a estrutura do manifesto, os plugins referenciados e os limites de arquitetura:

```bash
npx @fayz-ai/cli doctor
```

Um `id` fora do padrão ou uma surface sem `scaffold` fazem o doctor sair com erro — de propósito, para você pegar o problema antes de subir. Hoje o doctor valida a **estrutura** do manifesto e as fronteiras de arquitetura; a validação dos *valores* de enums (como `backend.provider` ou `theme.brand`) está chegando — um fix de SDK está em PR.

---

Próximo: aplique a sua marca em [Temas](/pt-BR/docs/apps/temas).