> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronização em tempo real

> Apps locais com suporte offline e sincronização automática em background.

## Como funciona

Apps com sincronização em tempo real mantêm um banco de dados local no dispositivo. Leituras são instantâneas (locais), escritas ficam na fila localmente, e tudo sincroniza com o servidor em background.

```text theme={"theme":"material-theme-darker"}
Escrita do usuário -> Banco de dados local -> Fila de upload -> Servidor -> Postgres
                                                                              |
Leitura do usuário  <- Banco de dados local <- Replicação de sync <---------+
```

O resultado: leituras instantâneas, sem spinners de carregamento, e um app que continua funcionando em conexões ruins ou offline.

## O que a IA configura

Peça à IA para construir um app em tempo real. Ela reutiliza um banco de dados ativo adequado quando existe; caso contrário, cria um banco de dados, ativa o serviço de sync e constrói um app em duas partes:

* **UI** - app cliente com banco de dados local, consultas ao vivo e conector de sincronização
* **Process** - endpoint de token, rota de upload de sync e executor de migrações

Credenciais são armazenadas no [vault](/work/vault). A IA conecta variáveis de ambiente do banco de dados ao componente de processo com a ferramenta `db`.

Antes do app ser considerado pronto, o banco de dados deve mostrar `sync: ready`. Se o sync não estiver pronto, o app pode renderizar, mas dados em tempo real entre dispositivos não funcionarão.

## Regras práticas

* Escreva localmente primeiro. Deixe o sync fazer upload em background.
* Mostre estados vazios, não spinners de carregamento, uma vez que dados locais existem.
* Mantenha o estado visível ao usuário em tabelas sincronizadas para que sobreviva a atualizações e uso offline.
* Agrupe escritas locais relacionadas para que a UI atualize em uma única etapa.
* Verifique a saúde do sync antes de considerar um app em tempo real como pronto.

## Shell de app offline

Templates de UI podem incluir um shell de app offline para que o app possa reabrir após a primeira visita sem rede. O shell do app é o HTML, JS, CSS e ícones estáticos.

* **Shell offline** permite que o app abra sem rede
* **Sync** mantém os dados do app utilizáveis enquanto offline

Juntos: o app abre sem rede, mostra os dados sincronizados mais recentes, coloca novas escritas na fila e sincroniza quando a conexão volta.

## Quando usar sincronização em tempo real

| Bom ajuste                                  | Excessivo                         |
| ------------------------------------------- | --------------------------------- |
| Gerenciadores de tarefas e apps de notas    | Páginas de marketing estáticas    |
| Ferramentas colaborativas                   | Envios de formulário únicos       |
| Apps de campo com conectividade fraca       | Sites de brochura somente leitura |
| Qualquer coisa que deva parecer instantânea | Apps sem valor offline            |

## Variáveis de plataforma

Kazzle injeta um pequeno conjunto de variáveis de ambiente em cada processo de app automaticamente. Estas são separadas de seus próprios [segredos do vault](/work/vault).

| Variável                          | O que é                                           |
| --------------------------------- | ------------------------------------------------- |
| `PORT`                            | A porta na qual seu processo deve escutar         |
| `HOST`                            | O hostname para vincular (tipicamente `0.0.0.0`)  |
| `KAZZLE_API_URL`                  | URL base usada pelos helpers de runtime do Kazzle |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | URL de runtime de um componente irmão             |

### URLs de irmãos

Quando um app tem múltiplos componentes (ex: uma UI `web` e um processo `server`), Kazzle pode injetar URLs para componentes irmãos:

```
# Na parte "web":
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# Na parte "server":
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

Quando um irmão já está implantado, o valor injetado aponta para esse componente implantado. Caso contrário, aponta para o endereço de desenvolvimento atual para esse irmão.