> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Estrutura do projeto

Encontra as apps, os pacotes partilhados e as fronteiras entre eles.

## Instalação e configuração

Antes de qualquer etapa, leia [Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md) e [Noções básicas sobre terminal](https://supastack.dev/pt/docs/web/terminal-basics.md). Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Abra o package.json raiz no VS Code e navegue apps/web para o site, apps/mobile para Expo, apps/desktop para o shell da área de trabalho e pacotes para partes compartilhadas.

2. Na raiz do repositório, execute corepack pnpm --filter @supastack/web dev.

3. Abra http://localhost:3000. Esperado: o aplicativo Web inicia em apps/web enquanto os pacotes compartilhados permanecem neste mesmo repositório; a janela da área de trabalho envolve esse aplicativo Web em vez de conter um segundo produto.

O workspace pnpm contém Next.js em apps/web, Expo em apps/mobile e pacotes partilhados em packages. Corre comandos do workspace a partir da raiz do repo. As rotas da aplicação compõem módulos partilhados; o comportamento próprio do produto pertence ao produto consumidor.

Lê AGENTS.md e .ai/PROJECT_CONTEXT.md antes de mudar comportamento. Os espelhos de ficheiros em .ai/ explicam decisões e restrições que nem sempre são evidentes a partir de um componente isolado.

```
apps/web/app/       Routes and layouts
apps/web/src/       Web components and server composition
apps/mobile/        Expo application
packages/           Shared contracts and adapters
tests/              Cross-module and browser checks
docs/               Operational guides
```


## Comandos para copiar

Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.

```
corepack pnpm --filter @supastack/web dev
```


## Onde cada alteração pertence

Antes de editar, decida qual app ou pacote é o dono da alteração. A regra prática: se apenas uma superfície do produto precisa dela, coloque-a nesse app; se todas as superfícies precisam, coloque-a num pacote compartilhado em `packages/`.

O repositório Web e o monorepo All Platforms contêm todas as pastas abaixo. Uma compra standalone de Mobile ou Desktop contém apenas o seu próprio app — o código do servidor fica no repositório Web.

[Construa a sua primeira funcionalidade](https://supastack.dev/pt/docs/web/first-feature.md)

- Uma nova página de marketing ou landing page → `apps/web/app/` — o site público.
- Uma nova tela dentro do produto com login → `apps/web/app/` para a rota mais `apps/web/src/` para a lógica — as páginas compõem os pacotes compartilhados.
- Uma nova rota de API → `apps/web/app/api/` — a metade de servidor do app Web.
- Uma alteração que todos os apps compartilham — uma tabela de banco de dados, um contrato, um adaptador de provedor → a pasta correspondente em `packages/`.
- Uma tela exclusiva de telefone → `apps/mobile/` — ela fala com a API do app Web em vez de ter o seu próprio back-end.
- Um comportamento exclusivo de desktop → `apps/desktop/` — o shell Tauri envolve o app Web e quase nunca duplica a UI do produto.


## Fluxo de implementação

Começa pela rota que possui a ação do utilizador, segue o seu handler de servidor e depois inspeciona o pacote partilhado que chama. Um componente de UI não deve recriar resolução de workspace, autorização de faturação ou escolha de fornecedor.

Ao adicionar uma rota, decide se é pública ou autenticada. Resolve a propriedade autenticada no servidor antes de aceder a registos de utilizador e mantém credenciais de servidor fora dos imports de cliente.


## Verificação e resolução de problemas

Se o comando informar que nenhum projeto corresponde ao filtro, verifique se o terminal está na pasta que contém o pacote raiz.json. Se a porta 3000 já estiver em uso, pare primeiro o outro servidor Web local. Não procure um bate-papo na área de trabalho separado ou uma implementação de login; o shell da área de trabalho carrega o backend da Web.

Corre os testes relevantes e o typecheck depois de mudar um contrato de pacote. Inspeciona consumidores web e mobile ao mudar tipos partilhados. Um build web bem-sucedido por si só não estabelece compatibilidade com a app nativa.


## Seguinte

[Configuração](https://supastack.dev/pt/docs/web/configuration.md)