Documentação / TIP -- Technical Implementation Plan

TIP -- Technical Implementation Plan

Entrar

TIP -- Technical Implementation Plan

Pilot Status

Status

Draft

1. Objetivo

Este documento descreve o plano técnico de implementação do Pilot Status, incluindo arquitetura, estrutura de serviços, modelagem inicial, fluxos de processamento e organização de deploy.

2. Arquitetura Geral

Stack

  • TypeScript (Full Stack)
  • Next.js (Frontend + API Routes como BFF)
  • NextAuth (Google, GitHub)
  • Prisma ORM
  • PostgreSQL (Gerenciado)
  • Redis (Gerenciado)
  • BullMQ
  • Workers dedicados
  • Docker Multi-stage
  • VPS para deploy
  • Evolution API (envio WhatsApp)
  • Umami (analytics frontend e backend)

3. Estrutura de Serviços

Serviço Web (Next.js)

Responsável por:

  • UI (Dashboard, Templates, Logs, API Keys, Perfil, Admin)
  • API Routes
  • Autenticação
  • Validação de API Key
  • Rate limiting
  • Registro de mensagens
  • Recebimento de webhook interno

Serviço Worker

Responsável por:

  • Consumo das filas BullMQ
  • Processamento FIFO por tenant
  • Envio de mensagens via Evolution API
  • Atualização inicial de status

4. Modelo de Dados (Inicial)

Tenant

  • id
  • name
  • created_at

User

  • id
  • tenant_id
  • email
  • provider

ApiKey

  • id
  • tenant_id
  • environment (test | live)
  • key_hash
  • created_at
  • last_used_at

Template

  • id
  • tenant_id
  • environment
  • name
  • status

TemplateVersion

  • id
  • template_id
  • version_number
  • json_payload
  • approval_status
  • created_at

Message

  • id
  • tenant_id
  • template_version_id
  • environment
  • destination_number
  • status (queued | sent | failed | read)
  • correlation_id
  • created_at

Subscription (Plano)

  • id
  • tenant_id
  • plan (free | basic | pro)
  • status
  • period (mensal)
  • limit_monthly (300 | 700 | 3000)
  • limit_daily (apenas free: 10; basic/pro: null)
  • stripe_subscription_id (opcional)
  • current_period_start
  • current_period_end

PackagePurchase (Pacote)

  • id
  • tenant_id
  • package (1 | 2)
  • messages_added (300 | 1000)
  • amount
  • provider (stripe | pague_dev)
  • status
  • created_at

Uso (contagem para rate limit)

  • Contagem de mensagens consumidas no mês por tenant (para limite mensal).
  • Contagem de mensagens consumidas no dia por tenant (apenas plano Gratuito).
  • Saldo de mensagens de pacotes comprados aplicado ao limite mensal do período.

5. Fluxo de Envio

  1. Cliente chama endpoint /send
  2. API valida API Key
  3. Aplica rate limit
  4. Cria registro Message
  5. Envia job para fila do tenant
  6. Worker consome fila
  7. Worker chama Evolution API
  8. Webhook interno atualiza status

6. Rate Limiting

  • Aplicado por API Key.
  • Limites por plano:
    • Gratuito: 300 msg/mês e 10 msg/dia.
    • Basic: 700 msg/mês, sem limite diário.
    • Pro: 3000 msg/mês, sem limite diário.
  • Pacotes: mensagens do Pacote 1 (+300) e Pacote 2 (+1000) somadas ao limite mensal do plano no período.
  • Modo test no plano Gratuito: limitado a 10 mensagens/dia.
  • Sem retry automático.
  • Sem DLQ (MVP).

7. Ambientes

  • API Keys:
    • ps_test_xxxxx
    • ps_live_xxxxx
  • Filas separadas por ambiente
  • Templates podem ser promovidos de test para live

8. Observabilidade

Implementar:

  • Correlation ID por mensagem
  • Logs estruturados (JSON)
  • Monitoramento de filas
  • Métricas:
    • Tempo médio de envio
    • Taxa de falha
    • Volume por tenant
  • Umami para analytics de frontend e backend (eventos de uso, páginas, API)

9. Deploy

Estrutura Docker

  • web (Next.js)
  • worker
  • nginx (opcional)

Redis e PostgreSQL serão gerenciados externamente.

Deploy em VPS com:

  • Docker Compose
  • Variáveis de ambiente seguras
  • SSL via proxy reverso

10. Integração de Pagamentos

  • Stripe: checkout/assinatura para planos Basic e Pro; checkout one-time para pacotes (cartão). Webhooks para atualizar assinatura e confirmar pagamento.
  • Pague Dev: fluxo Pix para pacotes e pagamento único. Callbacks para creditar mensagens dos pacotes.
  • Webhooks/callbacks para ativar ou renovar plano e creditar mensagens de pacotes no tenant.

11. Fases de Implementação

Fase 1 -- Base

  • Autenticação
  • API Keys
  • Envio básico
  • Fila por tenant
  • Logs básicos

Fase 2 -- Templates

  • Versionamento
  • Aprovação admin
  • Promoção test → live

Fase 3 -- Observabilidade

  • Métricas internas
  • Dashboard avançado
  • Alertas

Fase 4 -- Planos, Pacotes e Pagamentos

  • Modelo de dados (Subscription, PackagePurchase, contagem de uso)
  • Rate limit por plano e pacotes
  • Integração Stripe (assinatura e pacotes em cartão)
  • Integração Pague Dev (Pix para pacotes e pagamento único)
  • UI de planos e pacotes

12. Riscos Conhecidos

  • Sem estratégia de backup
  • Sem retry automático
  • Redis único compartilhado
  • Sem rotação de API Key

Conclusão

Este TIP define o plano técnico para implementação do MVP do Pilot Status, priorizando simplicidade, isolamento lógico multi-tenant e escalabilidade gradual.