Arquitetura do Sistema

Visão Geral

x17 é uma plataforma SaaS multi-tenant de WhatsApp Marketing. Permite que marcas conectem seu número WhatsApp, criem automações visuais (estilo n8n), enviem campanhas em massa, gerenciem contatos/conversas, e integrem com plataformas de e-commerce.

                                   +-----------------+
                                   |   Vercel CDN    |
                                   |  (Next.js 16+)  |
                                   +--------+--------+
                                            |
                     +----------------------+----------------------+
                     |                      |                      |
              +------+------+      +--------+--------+    +--------+--------+
              |   Pages /   |      |   API Routes    |    |   Cron Jobs     |
              | React 19 UI |      | /api/**         |    | Vercel Cron     |
              | (SSR + CSR) |      | (148+ routes)   |    | pg_cron         |
              +------+------+      +--------+--------+    +--------+--------+
                     |                      |                      |
                     |            +---------+---------+            |
                     |            |                   |            |
              +------+------+    |   +------------+  |   +--------+--------+
              |  Supabase   |<---+-->| Reposit.   |  |   |  Automation     |
              |  Browser    |    |   | Pattern    |  |   |  Engine         |
              |  Client     |    |   +------------+  |   | (trigger ->     |
              +-------------+    |                   |   |  step -> step)  |
                                 |   +------------+  |   +--------+--------+
                                 +-->| Admin      |  |            |
                                 |   | Client     |  |   +--------+--------+
                                 |   | (service   |  |   |  Event System   |
                                 |   |  role key) |  |   | (emitEvent ->   |
                                 |   +------+-----+  |   |  dispatch)      |
                                 |          |         |   +--------+--------+
                                 +----------+---------+            |
                                            |                      |
                     +----------------------+----------------------+
                     |                      |                      |
              +------+------+      +--------+--------+    +--------+--------+
              |  Supabase   |      | Upstash Redis   |    |     VPS         |
              |  PostgreSQL |      | (sa-east-1)     |    | Claude Proxy    |
              |  + RLS      |      | Rate Limiting   |    | (FastAPI)       |
              |  + pg_cron  |      | Exec Limiter    |    | AI Features     |
              +------+------+      +-----------------+    +--------+--------+
                     |                                             |
              +------+------+                             +--------+--------+
              |  Supabase   |                             |  Anthropic API  |
              |  Storage    |                             |  (Claude)       |
              +-------------+                             +-----------------+

              Serviços Externos:
              +------------------+  +-----------------+  +------------------+
              | Meta/Facebook    |  | ASAAS (billing) |  | 17track          |
              | WhatsApp Cloud   |  | PIX, Boleto,    |  | (rastreamento)   |
              | API v23.0        |  | Cartão          |  |                  |
              +------------------+  +-----------------+  +------------------+
              +------------------+  +-----------------+  +------------------+
              | Shopify          |  | Yampi           |  | Nuvemshop        |
              +------------------+  +-----------------+  +------------------+
              +------------------+  +-----------------+  +------------------+
              | WooCommerce      |  | Hotmart         |  | Kiwify           |
              +------------------+  +-----------------+  +------------------+

Stack Tecnológico

Camada	Tecnologia
Frontend	Next.js 16+ / React 19 / TypeScript / Tailwind 4
UI	shadcn-ui / Zustand / Recharts / @xyflow/react
Backend	Next.js API Routes (148+ rotas)
Database	Supabase PostgreSQL + Row Level Security (RLS)
Auth	Supabase email/password via @supabase/ssr
Cache/Queue	Upstash Redis (rate limiting, execution limiter)
AI	VPS FastAPI proxy -> Anthropic Claude API
WhatsApp	Meta WhatsApp Cloud API v23.0 (Embedded Signup)
Billing	ASAAS (PIX, Boleto, Cartão de crédito)
Tracking	17track API (rastreamento de envios)
Deploy	Vercel (frontend) + Supabase (database) + VPS (AI)
Validação	Zod 4
i18n	pt-BR, en, es

Camadas da Aplicação

1. Frontend (React 19 + Next.js)

• Server Components para páginas (SSR)
• Client Components para interatividade (stores Zustand, forms)
• Editor de automações visual com @xyflow/react (clone visual do n8n)
• Chat em tempo real em /app/chat

2. API Routes (src/app/api/)

• 148+ rotas organizadas por domínio
• Pattern: getAuthContext() -> validação Zod -> repository/service -> response helpers
• Error handling centralizado via withErrorHandling() ou try/catch + error()
• Rate limiting via Upstash Redis em rotas críticas

3. Repositories (src/lib/repositories/)

• BaseRepository<T> abstrato com CRUD genérico
• Account-scoped por padrão (accountScoped = true)
• Páginação offset-based e cursor-based
• Soft delete para entidades com deleted_at
• Singletons exportados: contacts, templates, automations, etc.

4. Services / Domain Logic

• Motor de automações (src/lib/automations/)
• Sistema de eventos (src/lib/events/)
• WhatsApp integration (src/lib/whatsapp/)
• E-commerce integrations (src/lib/integrations/)
• VPS/AI client (src/lib/vps/)

5. Database (Supabase PostgreSQL)

• 66+ migrations SQL
• RLS policies em todas as tabelas (isolamento multi-tenant)
• pg_cron jobs: recalculate_all_segments (5min), execute-scheduled-campaigns (1min)
• Supabase Storage para media (template-media bucket)

Estrutura de Diretórios Relevante

src/
  app/
    api/                    # 148+ API routes
      automations/          # CRUD + resume + cron
      whatsapp/webhook/     # Webhook principal WhatsApp
      contacts/             # CRUD contatos
      templates/            # CRUD + submit para Meta
      campaigns/            # CRUD + send + cancel
      integrations/         # Shopify, Yampi, etc.
      cron/                 # Automations, billing
    (app)/                  # Pages protegidas (/app/*)
  lib/
    api/
      auth.ts               # getAuthContext()
      response.ts           # success(), error(), withErrorHandling()
      rate-limit.ts         # Upstash Redis rate limiter
      audit.ts              # Audit logging (fire-and-forget)
    automations/            # Motor de automações (17 arquivos)
    events/                 # Sistema de eventos (4 arquivos)
    whatsapp/               # Meta Cloud API (3 arquivos)
    integrations/           # E-commerce (6 plataformas)
    repositories/           # BaseRepository + especializados
    supabase/               # Clients (browser, server, admin, middleware)
    vps/                    # Claude Max Proxy client
    errors.ts               # Hierarquia de erros
    constants.ts            # Constantes globais
  types/
    database.ts             # Tipos TypeScript (700+ linhas)

Fluxos Principais

Mensagem WhatsApp recebida

Meta Webhook -> POST /api/whatsapp/webhook
  -> Validação HMAC (x-hub-signature-256)
  -> Lookup phone_number_id -> whatsapp_profiles -> account_id
  -> Upsert contato (UNIQUE: account_id + phone)
  -> Upsert conversa
  -> Inserir mensagem
  -> emitEvent("Message Received")
  -> dispatchTrigger("message_received")
  -> handleAutoReply() (chatbot IA)

Execução de automação

Trigger disparado (webhook/evento/cron)
  -> dispatchTrigger(accountId, triggerType, data)
  -> Buscar automações ativas com trigger_type correspondente
  -> Verificar match conditions (trigger registry)
  -> Verificar re-entry (once/always/cooldown)
  -> Verificar chain depth (max 5)
  -> Verificar concurrency limit (Upstash Redis, max 10)
  -> executeAutomation()
    -> Criar execution record
    -> Loop: step -> filter -> execute -> next_step
    -> Se wait > 30s: suspend + resume via cron
    -> Status final: completed/failed/suspended

Envio de campanha

POST /api/campaigns/[id]/send
  -> Buscar contatos do segmento
  -> Smart Sending check (quiet hours, frequency cap)
  -> Para cada contato: sendWhatsAppTemplate()
  -> emitEvent("Campaign Sent") por contato
  -> Atualizar stats da campanha

Segurança

• Headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy
• Auth: Supabase JWT, validação server-side em toda API route
• RLS: Isolamento de dados por account_id no PostgreSQL
• Encryption: AES-256-GCM para access tokens WhatsApp e integração
• Rate Limiting: Upstash Redis com presets (auth: 5/min, api: 30/min, webhook: 100/min)
• HMAC: Validação de assinatura em webhooks (WhatsApp, Shopify, etc.)
• SSRF Protection: Bloqueio de IPs internos em HTTP Request step

Documentos Relacionados

• auth-flow.md - Autenticação e autorização
• multi-tenant.md - Arquitetura multi-tenant
• automation-engine.md - Motor de automações (COMPLETO)
• event-system.md - Sistema de eventos
• whatsapp-integration.md - Integração WhatsApp Cloud API
• integrations.md - Serviços externos