# Arquitetura

URL canônica: https://texttree.ai/pt-br/docs/arquitetura/
URL em Markdown: https://texttree.ai/pt-br/docs/arquitetura.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumo

Como Astro, Phoenix, Neon, Oban e adaptadores de fornecedores se encaixam na versão alfa atual do TextTree.

## Conteúdo fonte

# Arquitetura

O site público e o ambiente de execução do aplicativo são deliberadamente separados.

## Superfície pública

Astro é responsável por:

- páginas de destino
- documentação
- blog
- Geração de metadados SEO, RSS e sitemap

## Superfície de aplicação

A Fênix é responsável por:

- login e experiência de usuário autenticado
-`/api/v1/*`
- webhooks assinados de provedores
-`/mcp/*`

## Estado central

Postgres desenvolvido por Neon é o sistema de registro para:

- usuários nativos do Phoenix e identidades de autenticação TextTree
- contas de agente sem cabeça com base no nome de usuário
- usuários e espaços de trabalho
- metadados de consentimento/contatos herdados
- exclusões de espaços de trabalho e campanhas
- mensagens
- entradas contábeis e limites de gastos
- eventos de fornecedores
- sessões de financiamento
- Auditorias de execução do MCP

## Responsabilidade dos trabalhadores

Oban é responsável pelos efeitos colaterais e novas tentativas.

- as mensagens de saída são enfileiradas antes da execução no provedor
- os eventos do fornecedor são armazenados antes da reconciliação
- caminhos de repetição e nova tentativa são mantidos fora dos controladores e LiveViews

## Regras de execução

As mensagens de saída seguem uma rota estrita:

1. verificação de exclusão do espaço de trabalho
2. reserva de despesas e escritura no livro contábil
3. colagem em Oban
4. execução no provedor dentro de um trabalhador

Isso mantém os efeitos colaterais externos fora dos controladores e LiveViews.

## Regras de webhook

Os webhooks do provedor seguem um limite paralelo:

1. verificação de assinatura
2. persistência de eventos normalizados
3. detecção de duplicatas
4. colagem em Oban
5. reconciliação na mensagem, exclusão ou status de financiamento

## Regras do MCP

A pegada do MCP é intencionalmente reduzida na versão alfa:

1. Inicialização de saúde pública e contas sem cabeça
2. Autenticação de token de portador TextTree para caminhos de ferramentas
3. aplicação de escopos no nível da rota
4. registro do servidor e verificações da lista de permissões
5. Controles de cota e tempo de espera
6. Logs de auditoria de execução persistente

Bootstrap contas headless via `/api/v1/accounts` ou `/mcp/accounts` cria
uma conta de agente com nome de usuário/senha, códigos de backup únicos e um portador de token
por TextTree. A limitação de bootstrap armazena um endereço IP com hash e permite apenas um
Criação bem-sucedida de conta por IP a cada cinco minutos.

## Limites do fornecedor

Controladores e LiveViews não ligam diretamente para os provedores.

- rotas de mensagens se comunicam com o contexto de mensagens
- as rotas de financiamento comunicam-se com o contexto de financiamento
- a semântica HTTP específica do provedor é mantida nos adaptadores do provedor
- a normalização do webhook ocorre antes da reconciliação do estado do negócio

## Restrições da versão Alfa

Esta arquitetura já é utilizável, mas permanece intencionalmente incompleta:- os ADRs locais do repositório capturam a linha de base de implantação atual enquanto a importação canônica do canvas ainda está pendente
- algumas superfícies de produtos são apenas para operadores e não para contratos públicos de API
- As ferramentas MCP são configuradas no servidor, não por locatário
- a documentação descreve o contrato alfa implementado, não promessas de um roteiro futuro