Stack Tecnológica (detalhe)
Duas stacks separadas operam no projeto Master Espresso. Não confundir.
Duas stacks · contextos diferentes
Seção intitulada “Duas stacks · contextos diferentes”| Contexto | Stack | Quem usa |
|---|---|---|
| App real (produto entregue ao Cliente Master Espresso) | Next.js 15 (App Router + Server Actions) + TypeScript + Tailwind CSS v4 + Shadcn/ui + Supabase (Postgres + Auth) + Pagar.me (Pix Automático + cartão recorrente, ratificado 2026-06-09) + ViaCEP | Assinante final · Operador Master Espresso · Admin |
| Site / docs (este site — spec, roadmap, capacidades) | Astro 5 + Starlight 0.37 + React/Svelte islands (Vercel AI SDK v6 + assistant-ui pro chat sample) + Recharts + PGlite (.ops boot) | Cliente Master Espresso · Fernando · Mukutu Circle · dev-team · claude-agent |
A stack do site é infra de spec — escolhida pra render eficiente de conteúdo estruturado + Gen UI samples. A stack do App é conforme BRIEF Fernando — Next.js 15 + Tailwind v4 + Shadcn é o que será entregue em produção.
Stack App real · componentes decididos
Seção intitulada “Stack App real · componentes decididos”Total: 6 componentes ativos no App real — todos decididos. Gateway Pagar.me ratificado em 2026-06-09 (Pix Automático + cartão recorrente). Tudo abaixo refere-se ao App entregue ao cliente, não à stack do site de docs.
Pagamento — Pagar.me canonical (Pix Automático + cartão recorrente) ✅
Seção intitulada “Pagamento — Pagar.me canonical (Pix Automático + cartão recorrente) ✅”Componentes decididos firmes
Seção intitulada “Componentes decididos firmes”Next.js 15 + TypeScript — fullstack
Tecnologia: Next.js 15 (App Router + Server Actions)
Justificativa: Framework full-stack React 19 com TypeScript estrito; App Router pra SSR/RSC + Server Actions pra mutations sem rota API. Stack canonical do App real conforme BRIEF Fernando.
Tailwind CSS v4 — frontend
Tecnologia: Tailwind CSS v4 (Oxide engine + CSS-first config)
Justificativa: Utility-first com engine Oxide (Rust) — build ~10× mais rápido que v3. Config via @theme em CSS nativo. Pareia direto com Shadcn/ui (suporte v4 oficial). Stack canonical conforme BRIEF Fernando.
Shadcn/ui — ui_library
Tecnologia: Shadcn/ui (Radix UI + Tailwind v4)
Justificativa: Componentes copy-paste baseados em Radix UI primitives + Tailwind v4. Não é dependência npm — é código no repo (full control). Stack canonical conforme BRIEF Fernando.
Supabase — banco_dados
Tecnologia: Supabase (PostgreSQL + Auth)
Justificativa: BaaS com PostgreSQL gerenciado e autenticação integrada (Magic Link, OAuth)
Pagar.me (Pix Automático + cartão recorrente) — gateway_pagamento
Tecnologia: Pagar.me
Justificativa: Gateway brasileiro (BRL nativo, regulado pelo BACEN) com suporte nativo ao Pix Automático (Bacen, fluxo de cobrança recorrente via Pix) E cartão recorrente tokenizado na mesma API. Score 8/10 agentic (sandbox instantâneo, docs API-first, NF-e via integração). Pix e cartão são opções gêmeas no checkout — assinante escolhe. Ratificado por Gabriel 2026-06-09 (Lane X research).
ViaCEP — validacao_cep
Tecnologia: ViaCEP API
Justificativa: API REST gratuita para lookup de CEP; usada na restrição Grande SP em T06 + T09
Critério da decisão Pagar.me vs alternativas (Lane X research 2026-06-09)
Seção intitulada “Critério da decisão Pagar.me vs alternativas (Lane X research 2026-06-09)”| Critério | Pagar.me (escolhido) ✅ | Asaas (demoted) | Stripe (rejeitado) | MercadoPago (fallback) |
|---|---|---|---|---|
| Pix Automático recorrente | Nativo (Bacen) | Sim (Pix recorrente) | Não suporta em BR | Sim |
| Cartão recorrente tokenizado | Nativo na mesma API | Sim | Sim | Sim |
| Moeda | BRL nativo | BRL nativo | USD-fee + conversão | BRL nativo |
| Score agentic (DX) | 8/10 (sandbox instantâneo, API-first) | 6/10 | 9/10 mas sem Pix Automático | 5/10 |
| NF-e | Integração c/ provider fiscal (eNotas/NFE.io) | Integrada na API | Provider fiscal externo | Integração externa |
| Mercado | BR (BACEN regulado, Stone group) | BR (BACEN regulado) | Internacional | BR/LATAM |
| Custo Pix Automático | ~0,99% | ~1,49% | — | ~0,99% |
| Custo cartão recorrente | 2,99% + R$0,29 | 2,49% + R$0,29 | 3,99% + R$0,39 + USD-fee | 3,79% + R$0,39 |
Pivot path: caso sandbox Pagar.me falhe em S2 (improvável, mas guarda), o adapter
PaymentGatewaypermite swap pra MercadoPago em ~1 dia sem retrabalho de schema. Stripe e Asaas ficam apenas como referência histórica.
Alternativas arquivadas
Seção intitulada “Alternativas arquivadas”Componentes considerados mas não adotados — mantidos para referência caso a decisão precise ser revisitada.
Stripe (alternativa rejeitada) — gateway_pagamento (rejeitada)
Tecnologia: Stripe
Justificativa do arquivamento: Demoted — não suporta Pix Automático recorrente em BR (hard blocker per X research 2026-06-09). Mantido como referência apenas. USD-fee + NF-e externa também pesavam contra.
Sumário por Categoria
Seção intitulada “Sumário por Categoria”| Categoria | Componente | Status |
|---|---|---|
| fullstack | Next.js 15 + TypeScript | ✅ decidido |
| frontend | Tailwind CSS v4 | ✅ decidido |
| ui_library | Shadcn/ui | ✅ decidido |
| banco_dados | Supabase | ✅ decidido |
| gateway_pagamento | Pagar.me (Pix Automático + cartão recorrente) | ✅ decidido |
| validacao_cep | ViaCEP | ✅ decidido |