Proposta Técnica

📋 Copiar para Google Docs

Proposta Técnica — Master Espresso

1. Princípios da escolha

• Zero infraestrutura própria. Runtime 100% gerenciado.
• Gateway nacional com Pix Automático recorrente nativo.
• Escala até 1.000 assinantes sem refactor.
• Lock-in aceito quando elimina operações sem valor direto ao produto.
• Gateways internacionais descartados: não suportam Pix Automático no Brasil.

2. Stack da aplicação

Versões pinadas no package.json por versão (v0.1 → v0.6). Atualização de libs = manutenção, não release de feature.

2.1 Frontend e Backend

Next.js 16 (App Router + Server Actions) + Tailwind CSS v4 + shadcn/ui (CLI 4.11). Server Actions eliminam BFF separado. Hot path abaixo de 100 ms em Vercel Edge.

2.2 Banco de dados e autenticação

Supabase v2 (PostgreSQL + magic-link). Row-Level Security isola assinantes sem código extra. Pro inclui PITR 7 dias + snapshots diários 30 dias.

2.3 Gateway de pagamento

Pagar.me v5 — Pix Automático e cartão tokenizado na mesma API. Adapter PaymentGateway permite troca para MercadoPago em ~1 dia. Stripe descartado (sem Pix Automático BR); Asaas descartado (DX inferior).

2.4 Validação de endereço

ViaCEP (gratuita, sem chave) para preenchimento por CEP. Lista hardcoded de 39 municípios da RMSP (IBGE) como gate de cobertura — mantida no repositório como constante, atualização exige deploy.

2.5 E-mail transacional

Resend v6 — free tier (100/dia) cobre lançamento. Upgrade Pro ($20/mês) quando saturar.

2.6 Logística e catálogo

Melhor Envio API para cotação e etiquetas; fallback manual via CSV. Catálogo: JSON seed versionado em Git; operador edita via Supabase Studio.

2.7 Observabilidade

• Sentry — erros runtime server + browser. Stacktrace + breadcrumbs por usuário.
• Better Stack — uptime HTTP 30 s multi-região + status page público + alerta Discord/SMS.
• PostHog — eventos de produto (funil, retenção, click-tracking opt-in). Sem PII.

Sentry pega erro depois que request entra; Better Stack pega quando request nem chega.

3. Infraestrutura

Zero servidor próprio. Zero container. Zero Kubernetes.

3.1 Arquitetura

flowchart LR
    Assinante["Assinante<br/>(Browser)"] --> Edge["Vercel Edge<br/>CDN + WAF"]
    Edge --> App["Next.js 16<br/>Server Actions"]

    subgraph Dados["Plano de dados"]
        App <-->|SQL| Supa[("Supabase<br/>Postgres + Auth")]
        App -->|CEP| ViaCEP["ViaCEP"]
    end

    subgraph Controle["Plano de controle"]
        Pagar["Pagar.me"] -.->|webhook| App
        App --> Resend["Resend<br/>Email"]
        App --> Envio["Melhor Envio"]
    end

    subgraph Obs["Observabilidade"]
        Sentry["Sentry"]
        BetterStack["Better Stack"]
        PostHog["PostHog"]
    end

    App -->|erros| Sentry
    App -->|uptime| BetterStack
    App -->|eventos| PostHog

3.2 Fluxo de cobrança recorrente

sequenceDiagram
    participant C as Assinante
    participant N as Next.js
    participant P as Pagar.me
    participant S as Supabase
    participant R as Resend
    C->>N: Confirma assinatura (Pix ou cartão)
    N->>P: Cria recorrência
    P-->>N: Token + agendamento
    N->>S: Persiste subscription + payment_method
    Note over P: Mensalmente, dia 10
    P->>N: Webhook charge.paid
    N->>S: Atualiza subscription.last_charge_at
    N->>R: Envia comprovante
    R-->>C: E-mail de confirmação

charge.paid é a única fonte de verdade para status de pagamento. Idempotência via charge_id na tabela payment_events.

4. Backups e continuidade

• PITR: Supabase Pro, RPO ~2 min. Snapshot diário, retenção 7 dias.
• Backup frio: GitHub Action semanal — pg_dump → Cloudflare R2 (retenção 90 dias, ~$1/mês).
• Restore drill mensal: pg_dump prod → Supabase Preview Branch ephemeral. Smoke SELECT count(*) em assinaturas, pagamentos, clientes. Alerta Discord se drift >5% ou restore falhar.
• Catálogo + assets: JSON + imagens versionados em Git. Recuperação = git checkout + redeploy.
• Métricas: RPO 2 min (PITR) · 24 h (frio). RTO <30 min.

5. Deploy e atualização

• Blue-green leve: cada deploy Vercel ganha URL única; promoção = swap atômico de DNS. Sem janela de manutenção.
• Rollback instantâneo: Vercel reverte código em segundos. Rollback de código não desfaz migration — combinar com PITR quando migration for destrutiva.
• Migrations zero-downtime (expand-contract): 1) adicionar coluna nullable, 2) código escreve em ambas (antiga + nova), 3) backfill em batches (LIMIT), 4) switch reads para nova, 5) drop coluna antiga na release seguinte. CREATE INDEX CONCURRENTLY e NOT VALID constraints evitam locks longos.
• Preview por PR: Supabase Branching — cada PR ganha DB ephemeral com migrations aplicadas.
• Feature flags: Vercel Edge Config (<15 ms P99).

6. Projeção de custos por fase

Versão	Assinantes	Vercel	Supabase	Resend	Observ.+Backup	Total/mês
v0.1 Assinar	0–10	Hobby (free)	Free	Free	—	$0
v0.2–0.3 Painel	10–100	Pro $20	Pro $25	Free	$1 (R2)	$46
v0.4–0.6 Operação	100–500	Pro $20	Pro $25	Pro $20	$53 (Sentry+BStack+R2)	$118

Taxas Pagar.me separadas (~2% Pix · ~3% cartão por transação).

7. Decisões de não-fazer

• Sem Kubernetes/containers. Vercel + Supabase cobrem o runtime.
• Sem painel admin customizado. Supabase Studio + Generative UI.
• Sem CMS dedicado. Catálogo JSON + Supabase Studio.
• Sem self-host de observabilidade. Free tiers gerenciados.
• Sem multi-tenant. Instância única.
• Sem SMS. E-mail transacional cobre comunicação.

8. Estimativa de manutenção

Tarefa	Frequência	Tempo
Atualizar Next.js 16 + Astro 6 + libs	Mensal	1 h
Verificar backups + restore drill	Mensal	1 h (automatizado)
Rotação de chaves de API	Semestral	0,5 h/sem.
Migration zero-downtime	Por release	1 h

Total esperado: 3,5 h/mês. Zero pager fora de horário comercial — managed services (Vercel, Supabase, Pagar.me, Resend) mantêm 99,9%+ de SLA.

📋 Copiar para Google Docs