Skip to main content

​
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