Core

Contas, tenants e a árvore.

Asender Core - Aplicacao Principal

Spec da aplicacao principal multi-tenant do Asender. Este eh o SaaS que os customers acessam (dashboard + API), diferente dos relays edge.

Status:

• Fase 2 (foundation: auth, tenancy, API keys, invitations, relay management, webhooks) - IMPLEMENTADO
• Fases 3+ (SMTP, templates, campanhas, SMS, push, analytics, billing) - em planejamento

Codigo: ../asender-core/

1. Escopo

Servicos Oferecidos

1. Email / SMTP - transacional + bulk + SMTP externo (usar como relay pra terceiros)
2. SMS - disparos via gateways
3. Push - mobile + web push

Funcionalidades Transversais

• Dashboard web de gestao
• API REST publica (SES-compatible + extensoes)
• Webhooks de eventos
• Campanhas com agendamento e A/B
• Templates visuais
• Contatos e listas com segmentacao
• Analytics e relatorios
• Billing e quotas
• Multi-tenancy completo

2. Stack

Proposta

• Backend: Laravel 11 (PHP 8.3)
• DB principal: PostgreSQL 16
• Cache/Queue: Redis + Laravel Horizon
• Events store: ClickHouse (eventos em massa pra analytics)
• Object storage: S3-compatible (R2/Spaces/S3/MinIO)
• Frontend: Inertia.js + Vue 3 + TailwindCSS
• Email editor: MJML + component library custom
• Search: Meilisearch (contatos, templates, logs)
• Containers: Docker + Docker Compose (dev), Kubernetes (prod)

Por que Laravel?

• Ecossistema PHP coerente com o relay
• Horizon pra filas robusto
• Sanctum/Passport pra auth de API
• Telescope pra debug
• Inertia pra SPAs sem API separada
• Comunidade grande

3. Modulos

3.1 Auth & Tenancy

Entidades:

• User (pessoa fisica que loga)
• Tenant (empresa/conta, chamado de "organization" no UI)
• TenantUser (pivo com role)
• ApiKey (tokens de API, scoped ao tenant)
• Invitation (convites pendentes)

Features:

• Registro com confirmacao de email
• Login + 2FA (TOTP)
• SSO via OAuth (Google, Microsoft)
• SSO via SAML (enterprise)
• Convites por email com role
• Roles: owner, admin, developer, viewer
• API keys scoped: full_access, send_only, read_only
• Audit log de acoes sensiveis

Multi-tenant resolution:

• Por subdominio: acme.asender.io
• Por API key (determina o tenant)
• Middleware EnsureTenant injeta $tenant em request

3.2 Dominios e Reputacao

Entidades:

• Domain (dominios de envio verificados)
• DkimKey (chaves DKIM por dominio)
• SuppressionList (bounces + complaints + unsubscribes)

Features:

• Adicionar dominio com verificacao (TXT DNS)
• Geracao automatica de DKIM (2048 bits)
• Instrucoes passo-a-passo de config DNS (SPF, DKIM, DMARC)
• Validacao periodica de DNS
• Verificacao de reputacao (blacklists publicas)
• Warm-up automatico de novos IPs

3.3 SMTP / Email Module

Entidades:

• EmailMessage (mensagem enviada ou agendada)
• EmailEvent (open, click, bounce, complaint, etc)
• EmailTemplate (template com editor visual)
• EmailRelay (referencia a um relay PHP externo)
• Domain (ja listado acima)

Features:

• API de envio SES-compatible (/v1/emails/send)
• Envio direto via provedores SMTP parceiros (SES, SendGrid, Mailgun)
• Envio via relays proprios (PHP relay) pra IPs dedicados
• Tracking de opens (pixel) e clicks (redirect)
• Bounce processing via webhook dos provedores
• Complaint processing (FBL)
• Unsubscribe automatico (link no rodape + List-Unsubscribe header)
• Suppression list global por tenant
• SMTP gateway externo: cliente usa smtp.asender.io:587 como provider

Editor de templates:

• Drag-n-drop ou codigo MJML/HTML
• Preview em dispositivos
• Teste de envio
• Variaveis Handlebars-like
• Biblioteca de templates prontos
• Versioning

3.4 SMS Module

Entidades:

• SmsMessage
• SmsEvent (DLR)
• SmsGateway (config dos gateways por tenant)
• PhoneNumber (pool de numeros alugados)
• SuppressionList (opt-outs)

Gateways suportados (integracao):

• Twilio
• AWS SNS
• Zenvia (BR)
• Plivo
• MessageBird
• Custom HTTP gateway

Features:

• Envio 1:1 e em massa
• Agendamento
• DLR handling
• Opt-out automatico (STOP/SAIR)
• Suporte a Unicode e segmentacao automatica
• Pool de numeros (rotacao)
• Fallback entre gateways

3.5 Push Module

Entidades:

• PushMessage
• PushEvent (sent, delivered, opened, failed)
• Device (tokens FCM/APNs/WebPush)
• PushApp (app registration com chaves do tenant)
• Topic / Segment

Providers:

• FCM (Firebase Cloud Messaging) - Android
• APNs (Apple Push Notification service) - iOS
• Web Push (VAPID) - browsers

Features:

• Registro de devices via API (SDK cliente)
• Envio individual ou em massa
• Topics (publish a todos inscritos)
• Segments (filtros sobre devices)
• Silent push
• Badge/sound customization
• Analytics (delivery rate, click rate)

3.6 Campaigns Module

Entidades:

• Campaign (email, sms, push, ou multi-canal)
• CampaignRun (execucao especifica)
• CampaignRecipient (destinatario da execucao)
• Segment / List
• AbTest

Features:

• Builder visual de campanha
• Seleciona: canal, template, lista/segmento, agendamento
• Teste A/B: subject, conteudo, horario
• Throttling configuravel
• Rastreio individual por destinatario
• Relatorio pos-campanha
• Pause / resume / cancel
• Copy from previous

3.7 Contacts Module

Entidades:

• Contact (pessoa alcancavel)
• ContactField (campo custom definido pelo tenant)
• ContactValue (valores EAV ou jsonb)
• ContactList (listas)
• ContactListMember (pivo)
• Segment (consulta salva)

Features:

• CRUD de contatos
• Campos custom por tenant
• Listas estaticas e dinamicas (segments)
• Import CSV / JSON
• Export
• Deduplicacao por email/telefone
• Supressoes automaticas (quem deu bounce, nao eh adicionado)
• API de webhook pra sincronizar com CRMs

3.8 Automations (Flows)

Entidades:

• Automation (fluxo)
• AutomationStep (nos do fluxo)
• AutomationRun (execucao por contato)

Features:

• Trigger: signup, tag added, event received, scheduled, etc
• Steps: wait, send email/sms/push, update contact, branch (if), webhook
• Visual flow builder
• Histórico por contato

3.9 Analytics

Entidades (em ClickHouse):

• email_events (1 row por evento)
• sms_events
• push_events
• campaign_stats (aggregates materializadas)

Features:

• Dashboard com metricas principais
• Funil de engajamento (sent > delivered > opened > clicked)
• Comparacao entre campanhas
• Heatmaps de horarios
• Geolocation (com anonimizacao)
• Client breakdown (iOS/Android/Gmail/Outlook)
• Export CSV / API

3.10 Relay Management

Entidades:

• Relay (instancia de asender-relay-php)
• RelayHealth (historico de health checks)
• RelayTenant (mapping: relay X hosts tenant Y internally)

Features:

• Cadastrar relay existente (URL + master key)
• Provisionar novo relay automaticamente (via API de hosting)
• Health check periodico (/health endpoint)
• Sync de tenants: cada customer do Core ganha um tenant no relay apropriado
• Sync de templates importantes
• Agregacao de stats cross-relay
• Failover: se um relay cai, route pra outro

3.11 Billing

Entidades:

• Plan (tier de assinatura)
• Subscription
• UsageCounter (por tenant por periodo)
• Invoice
• PaymentMethod

Features:

• Planos: Free, Starter, Pro, Enterprise
• Metering: emails enviados, SMS, push, storage de anexos
• Overages ou hard limits
• Stripe pra cartao
• Pix/boleto (BR)
• Invoices PDF
• Usage dashboard no painel

3.12 Webhooks & Events

Entidades:

• WebhookEndpoint
• WebhookDelivery
• EventLog

Features:

• Customer cadastra URL + secret
• Eventos: email.sent, email.delivered, email.bounced, email.opened, email.clicked, sms.sent, sms.dlr, push.delivered, campaign.started, campaign.finished, etc
• Retry com backoff (3, 15, 60, 360 min)
• Signature HMAC-SHA256 no header
• Log de deliveries
• Resend manual

3.13 API Publica

Principios:

• REST-ish
• Versionada: /v1/
• Autenticada com API key
• Formato SES-compatible onde fizer sentido
• Respostas JSON com RequestId
• Erros formato SES ({Error: {Type, Code, Message}})

Principais endpoints:

POST   /v1/emails/send
POST   /v1/emails/send-batch
GET    /v1/emails/{id}
GET    /v1/emails
POST   /v1/emails/{id}/cancel

POST   /v1/sms/send
GET    /v1/sms/{id}

POST   /v1/push/send
POST   /v1/push/devices
GET    /v1/push/devices

GET    /v1/templates
POST   /v1/templates
PUT    /v1/templates/{id}
DELETE /v1/templates/{id}

GET    /v1/contacts
POST   /v1/contacts
PUT    /v1/contacts/{id}

GET    /v1/campaigns
POST   /v1/campaigns
POST   /v1/campaigns/{id}/start

GET    /v1/stats
GET    /v1/account

4. Data Model (high-level)

Ver DATA_MODEL.md pra schemas detalhados.

5. SDK Strategy

Cada SDK:

• Thin wrapper sobre a REST API
• Auth via env var: ASENDER_API_KEY
• Retries automaticos em 5xx
• Typed models
• Helpers: $asender->emails->send([...])

Prioridade: PHP > Node > Python > Go > Ruby

6. Deploy & Ops

Ambientes

• dev - local (docker-compose)
• staging - replica de prod, dados fake
• prod - multi-region, multi-AZ

CI/CD

• GitHub Actions
• Testes unitarios + feature
• Testes E2E (Playwright)
• Build de images Docker
• Deploy automatico pra staging, manual pra prod

Monitoring

• Logs: Loki ou CloudWatch
• Metricas: Prometheus + Grafana
• Errors: Sentry
• Uptime: UptimeRobot ou equivalente

Backup

• DB: daily + PITR (point-in-time recovery)
• Object storage: versionado
• Template/config: git

7. Segmentation do MVP

Nao vai dar pra lancar tudo de uma vez. Proposta de MVP:

MVP (3 meses)

• Auth + Tenancy basico
• Dominios + DKIM
• SMTP module core (envio simples via provedor direto)
• Templates basicos (sem editor visual, so codigo)
• API publica de envio
• Relay management basico
• Dashboard minimo (lista de emails + stats)

Pos-MVP (6 meses)

• Campanhas + agendamento
• Contatos + listas
• Editor visual de templates
• Webhooks de eventos
• Analytics dashboard

Expansao (12 meses)

• SMS module
• Push module
• Automations
• Billing
• A/B testing
• SSO enterprise