# Um Worker. Todo cliente.

Um starter full-stack para web e mobile. TanStack Start, Expo e uma API tipada, rodando na Cloudflare.

## Já em funcionamento.

Tarefas, arquivos, segurança e conexões de agentes. Telas reais do template com dados de exemplo.

[Documentação](/docs) · [Changelog](/docs/changelog)

## As peças que funcionam.

Mantenha o que o seu produto precisa. Toda integração abaixo está incluída; serviços opcionais ficam desligados até você configurá-los.

### Produto

- Autenticação (Pronto): E-mail e senha, passkeys, códigos de dois fatores, verificação de e-mail e gestão de sessão.
- Organizações (Pronto): Membros, convites e perfis. Tarefas e arquivos pertencem à organização ativa.
- Arquivos (Pronto): Uploads multipart para o R2, prévias, links de compartilhamento e lixeira.
- Administração (Pronto): Gestão de usuários, personificação, feature flags e log de auditoria.
- Exemplo de tarefas (Pronto): Visões em grade, quadro e calendário, com filas de importação por lock e rascunhos propostos por agentes de IA.
- Pagamentos (Desligado por padrão): Stripe e Polar na web, RevenueCat no mobile. Desligado até os provedores e as flags de cobrança estarem configurados.

### Plataforma

- Banco de dados (Pronto): Drizzle no Neon Postgres, acessado via Hyperdrive.
- E-mail (Pronto): E-mail transacional pelo Cloudflare Email, impresso no console em desenvolvimento.
- i18n e SEO (Pronto): Inglês, alemão e português, hreflang, sitemap e imagens OG geradas com Takumi.
- Assistente no app (Desligado por padrão): Chat em streaming com TanStack AI e ferramentas MCP compartilhadas. Desligado até um provedor estar configurado e a flag do assistente ligada.
- Tarefas agendadas (Pronto): Effect nas bordas: tarefas cron e entrega para fora, com locks no Postgres para a fila.
- Consentimento de cookies (Pronto): Um banner de consentimento que segura scripts de analytics e marketing.

### Mobile

- App Expo (Pronto): iOS e Android com o mesmo cliente da API, sessão e passkeys.
- Notificações push (Em andamento): Registro de push do Expo e fila de entrega. Desligado até as credenciais serem definidas.
- Widgets de tela inicial (Desligado por padrão): Widgets de tarefas para iOS e Android atrás de uma build nativa opcional.
- Anúncios (Desligado por padrão): Utilitários do AdMob mantidos como lib separada, não importados pelo app.

## Um contrato compartilhado.

O navegador e o Expo chamam o mesmo router oRPC. O Worker verifica a sessão antes de acessar Postgres ou R2.

- Web: TanStack Start, React, Tailwind CSS, shadcn/ui

- Mobile: Expo, Expo Router, React Native

- API: oRPC, Zod, Effect

- Auth: Better Auth

- Dados e arquivos: Drizzle ORM, Neon Postgres, Hyperdrive, R2

- Plataforma e ferramentas: Cloudflare Workers, GitHub Actions, Turborepo, pnpm

### apps/web/src/features/landing/landing.hooks.ts

```ts
import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/platform/rpc/orpc";

const { data: apiOk, isLoading: apiLoading } =
  useQuery(orpc.healthCheck.queryOptions());
```

Trecho da rota landing. O cliente gerado mantém a query tipada.

### apps/mobile/src/features/dashboard/dashboard.hooks.ts

```ts
import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/platform/rpc/orpc";

export function useBackendHealth() {
  return useQuery(orpc.healthCheck.queryOptions());
}
```

A tela inicial do Expo chama o mesmo procedimento de health-check.

### packages/api/src/platform/rpc/app-router.ts

```ts
healthCheck: publicProcedure.handler(() => {
  return "OK";
}),
```

Um health-check público. Procedimentos protegidos exigem adicionalmente uma sessão.

## Servidor continua servidor.

Compartilhe contratos com os clientes. Mantenha conexões de banco, segredos e código de servidor atrás de três checagens independentes.

- oxlint: Imports de valor de módulos de servidor falham no lint em apps/web, apps/mobile e packages/ui. Imports de tipo são permitidos.

- Exports explícitos: Cada pacote lista seus pontos de entrada públicos. Sem wildcards: um novo import entre pacotes é uma mudança deliberada.

- Varredura do bundle do cliente: O build web lê os assets do cliente e falha em strings que só existem no código do servidor.

## Um preview para cada PR.

Cada pull request ganha um Worker de preview e um branch no Neon. Revise na URL real e faça merge quando estiver pronto.

- Fazer merge publica em produção: Um push para main roda o workflow de produção separado, com segredos e banco de produção.

- A limpeza é precisa: Confere projeto, pull request e branch pai, apaga o Worker primeiro e aceita recursos que já sumiram.

## Um catálogo de ferramentas.

O TanStack AI e o servidor MCP usam as mesmas ferramentas autorizadas. Agentes de código recebem as instruções do repo e as decisões de arquitetura.

- AGENTS.md: Regras que todo agente de código lê primeiro: a fronteira cliente/servidor, Effect no servidor, i18n.

- docs/adr: Decisões de arquitetura com o contexto, para que um agente não as desfaça.

- .agents/skills: Setup, startup, deploy e verificação por browser como skills passo a passo.

- /api/mcp: Agentes leem seus dados e propõem rascunhos via OAuth. Os rascunhos esperam até você aplicá-los.

- /llms.txt: Markdown público em /index.md e um diretório /llms.txt para agentes lerem antes de se conectar.

## Faça seu.

Clone sua cópia do repositório. Instale, configure e rode web e mobile juntos.

### Clonar

Comece pela sua cópia do repositório do template.

```sh
git clone <your-repo-url> my-app
```

### Instalar

Instala todos os workspaces do monorepo.

```sh
pnpm install
```

### Configurar

Nomeia o projeto e escreve envs, Wrangler, banco, e-mail e armazenamento.

```sh
pnpm setup
```

### Rodar

Web em localhost:3005 e o servidor de dev do Expo para mobile.

```sh
pnpm run dev
```

## Antes de clonar.

### O que posso testar na demo?

Crie uma conta e use o app de verdade: tarefas, arquivos, organizações, passkeys, dois fatores e configurações. Ele roda no mesmo Worker desta página.

### Por que Cloudflare Workers?

Um deploy serve páginas, API, auth e jobs agendados. Cada pull request ganha o próprio Worker, então a revisão acontece em uma URL real.

### Por que Neon Postgres em vez de D1?

Auth, organizações e as filas de job dependem de transações e locks do Postgres. O Hyperdrive faz pool da conexão e cada PR ganha o próprio branch no Neon.

### Posso remover mobile, pagamentos ou anúncios?

Sim. optional-features.json lista cada pacote opcional e seus pontos de entrada, e docs/optional-features.md explica como removê-los.

### Como faço o rebrand?

Cores, raios e fontes vivem em um arquivo de tokens. Nomes e textos vivem nos arquivos de locale. As telas só usam tokens, então trocar a paleta muda toda página.

### Preciso saber Effect?

Só para mudar jobs de servidor. O Effect coordena a execução no Worker; contratos usam Zod, requisições usam oRPC, auth usa Better Auth e queries usam Drizzle.

### Como conecto um agente de IA?

Aponte qualquer cliente MCP para /api/mcp. Você aprova o acesso via OAuth, leitura e escrita são escopos separados e escritas só geram rascunhos que você confirma no app.

### O template inclui um assistente de IA?

Sim. O assistente e o MCP compartilham um único catálogo de ferramentas, com escopo na sua organização. Escritas exigem aprovação. Configure Anthropic, OpenAI ou Gemini e ligue a flag do assistente para exibir o chat. Vem desligado por padrão.