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

# Arquitetura para contribuidores

> Estrutura do repositório e limites de runtime para contribuidores.

# Arquitetura para contribuidores

Esta página apresenta a visão de arquitetura orientada a contribuidores. As páginas de arquitetura de produto vão mais a fundo na lógica de negócio; esta página responde a uma pergunta mais simples:

Onde um contribuidor deve fazer uma mudança?

## Apps ativos

* **`apps/app`**: UI do operador para inbox, contatos, templates, campanhas, journeys, configurações e visões de runtime.

* **`apps/web`**: site público e páginas próximas a marketing.

* **`apps/api`**: superfície de API em Next.js para endpoints internos, rotas de compatibilidade e o ingress atual da alpha hospedada na Vercel.

* **`apps/control-plane`**: runtime Node dedicado para trabalho de control-plane orientado a webhook e a fila. Permanece no repositório, mas não faz parte do contrato atual da alpha hospedada.

* **`apps/worker`**: loop de worker em segundo plano para processamento de outbox e reconciliação, destinado ao Railway na alpha.

* **`apps/storybook`**: workbench de componentes compartilhados.

## Packages compartilhados

* **`packages/auth`**: helpers de autenticação Supabase e infraestrutura de sessão
* **`packages/database`**: o único limite de data-plane suportado, incluindo contratos de repositório, adaptadores e responsabilidade voltada a migrations
* **`packages/design-system`**: primitivos de UI compartilhados
* **`packages/domain`**: contratos de domínio, dados mockados e parsing de env em runtime
* **`packages/feature-flags`**: helpers de flags e utilitários de toolbar
* **`packages/observability`**: logging e instrumentação leve de runtime
* **`packages/security`**: helpers de middleware de proxy/segurança
* **`packages/whatsapp`**: schemas de provider, validação de payload e constantes de restrição

## Limite do workspace ativo

A linha de release `0.1.x` suporta intencionalmente os workspaces ativos listados acima.

O repositório também mantém diversos apps e packages derivados do `next-forge` fora do conjunto de workspaces ativos. Esses arquivos são material de scaffold para ativação futura de funcionalidades, e ainda não fazem parte do contrato padrão de verificação.

## Divisão de runtime

Contribuidores devem pensar no repositório como três camadas de execução:

1. **Camada de frontend** em `apps/app`, `apps/web` e `apps/docs`
2. **Camada de request/HTTP** em `apps/api` e `apps/control-plane`
3. **Camada de processamento em segundo plano** em `apps/worker`

O Supabase é o data plane comum entre essas camadas.

## Onde colocar mudanças comuns

* Adicione tipos compartilhados ou contratos de domínio em `packages/domain`.
* Adicione validação de provider ou schemas de payload em `packages/whatsapp`.
* Adicione lógica de acesso a dados compartilhada em `packages/database`.
* Adicione UI reutilizável voltada ao operador em `packages/design-system`, com stories do Storybook.
* Adicione comportamento específico de rota no app que de fato é responsável pelo runtime.

## Observação sobre a implementação atual

* O repositório já possui uma baseline de schema Supabase e um contrato de auth/env.
* Muitas superfícies de produto visíveis para contribuidores ainda rodam sobre a camada de repositório com mock tipado.
* O repositório ainda não tem uma abstração de ORM verdadeira; não descreva o repositório dessa forma até que os adaptadores mock e Supabase estejam alinhados às mesmas interfaces de repositório.
* Ao alterar comportamento, documente se a mudança afeta o caminho mock, o caminho Supabase, ou ambos.

## Leia a seguir

* [Desenvolvimento](/pt-BR/development)
* [Limite de persistência](/pt-BR/contributing/persistence)
* [Arquitetura da plataforma](/pt-BR/platform/architecture)
* [Fluxo de contribuição](/pt-BR/contributing/workflow)