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

# Visão geral

> Como os serviços se conectam

# Arquitetura

BuildZero é um monorepo com 6 serviços e 3 packages compartilhados, conectados via event bus (QStash).

## Fluxo de uma mensagem

<Steps>
  <Step title="Telegram recebe mensagem">
    O webhook do Telegram Worker recebe a mensagem do usuário.
  </Step>

  <Step title="Gate autentica">
    O Telegram Worker chama o AI gate (Vercel) que valida o canal, identifica o usuário, e retorna tokens de sessão.
  </Step>

  <Step title="Bus publica evento">
    O Telegram Worker publica `message.received` via QStash para o AI Worker.
  </Step>

  <Step title="AI Worker processa">
    O AI Worker carrega histórico da sessão, cria o contexto com tools, e chama o Claude com streaming.
  </Step>

  <Step title="Streaming para Telegram">
    As respostas são enviadas em tempo real via edits progressivos na mensagem do Telegram.
  </Step>

  <Step title="Callback de conclusão">
    Ao finalizar, o AI Worker publica `message.response` de volta pro Telegram Worker para limpar a fila.
  </Step>
</Steps>

## Mapa de serviços

```
┌─────────────────────────────────────────────────┐
│                   Telegram Bot                   │
│              (Cloudflare Worker)                  │
└──────────┬──────────────────┬───────────────────┘
           │ gate             │ QStash
           ▼                  ▼
┌──────────────────┐  ┌──────────────────────────┐
│    AI Service    │  │      AI Worker           │
│    (Vercel)      │  │  (Cloudflare Worker)     │
│  auth + sessões  │  │  Claude + tools + stream │
└──────────────────┘  └────────┬─────────────────┘
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
              ┌─────────┐ ┌────────┐ ┌────────┐
              │ Daemon  │ │Sandbox │ │Meta API│
              │(WebSocket)│(Container)│(Graph) │
              └─────────┘ └────────┘ └────────┘
```