Arquitetura headless em 4 camadas
Cada camada com responsabilidade clara, dependência só na de baixo. Você troca a UI sem mexer no carrinho. Troca o backend sem reescrever providers.
Camada 4 — App / Storefront
App Next.js 15 que compõe as 3 camadas em uma loja real. App router (rotas dinâmicas via Supabase), middleware (auth/rate limit), CMS para edição visual, integrações com gateways de pagamento, SEO (sitemap, robots, metadata), deploy Vercel.
app routermiddleware.tsCMSpagamentossitemap/robotsVercel deploy Camada 3 — UI
Componentes opinados (Tailwind + Radix). ~20 componentes de domínio (ProductCard, CartDrawer, ProductFilters, HeroCarousel, etc.) + primitives. Tema via CSS vars HSL compatível com shadcn.
ProductCardCartDrawerProductGalleryProductFiltersGlobalHeaderFooter Camada 2 — React Providers & Hooks
Camada de cola entre os clientes headless e a UI. CartProvider, WishlistProvider, SupabaseAuthProvider, hooks de listagem e auth.
CartProviderWishlistProviderSupabaseAuthProvideruseCartuseWishlistuseProductsPage Camada 1 — Clientes Headless
Sem React, sem Next.js. Classes puras com auth/logger/fetcher injetáveis. Roda em qualquer runtime (Node, edge, worker).
OdooHttpClientProductServiceCartServiceSalesServiceAddressService Princípios de design
O que segura a coerência das libs.
Headless por padrão
Nenhuma lib (exceto a camada React e UI) conhece React, Next.js ou framework de UI. Tudo aceita fetch, auth, logger e storage como dependências injetadas.
Config explícito
Nenhuma lib lê process.env diretamente. URLs, secrets e flags chegam via construtor. Facilita testes e deploys multi-ambiente.
Substituível
Cada serviço é uma classe; o consumidor pode subclassear ou trocar por um mock em testes sem mexer no resto. Sem vendor lock-in interno.
Tipado e testado
TypeScript strict, ESM. Testes Vitest cobrem helpers puros, HTTP client, cart, JWT, rate limit, storage. CI verde no GitHub Actions.
Fluxo de dados típico
Do cliente abrindo a loja até o pedido confirmado.
Cliente abre o storefront
UI Next.js 15 SSR. Página de listagem busca produtos no Elasticsearch via ProductService (server-side).
Cliente busca um produto
UI → Headless Busca facetada no Elasticsearch. Resultados com collapse por modelo, brands, categorias, related products via Levenshtein.
Cliente faz login
Auth SupabaseAuthProvider abre fluxo Supabase. Token volta pro client + server. CartProvider sincroniza carrinho local com Odoo.
Cliente adiciona ao carrinho
React → Headless → Odoo useCart() chama CartService.addToCart(). Token Supabase atravessa pro Odoo via OdooHttpClient. Estado atualiza no React.
Checkout
Headless → Odoo AddressService busca endereços. DeliveryCarriersService calcula fretes. SalesService confirma pedido no Odoo. Fiscal nativo (NF-e/NFS-e).
Pagamento e fulfillment
Odoo Pagamento via Pix Cobrança / boleto-híbrido / cartão (gateway Odoo). Webhook bate no Odoo, libera fulfillment. Estoque desce.
Segurança e auth
Cookies HttpOnly, JWT, rate limit, logs estruturados.
Auth shopper via Supabase
Token JWT da Supabase atravessa para o Odoo via OdooHttpClient com getExtraHeaders. Sem replanilhar usuários, sem dois sistemas de senha.
Sessão admin com JWT em cookie HttpOnly
Pacote @kmee/admin-session: jose para JWT, helpers Next.js, getClientIp agnóstico de runtime, AdminRateLimiter com store plugável (memória default, Redis/KV em prod).
Rate limit configurável
Por IP, por endpoint, por usuário. Mitigação de brute force, abuso de API e scraping de catálogo.
Logs estruturados
Logger injetável com níveis. Fácil plugar no Datadog, Sentry, Grafana, ELK. Sem PII bruta nos logs por design.
Testes e CI
Vitest cobrindo helpers, HTTP, cart, JWT, rate limit, storage.
Vitest 4.x
Coverage v8, watch mode, snapshot, mock automático. Config única em vitest.config.ts na raiz do monorepo.
GitHub Actions
Pipeline em .github/workflows/test.yml: typecheck (tsc --noEmit) + tests + coverage report. Verde em cada PR.
Changesets
Versionamento e CHANGELOG via Changesets. PRs de release abertos automaticamente quando há mudanças em packages publicáveis.
Quer falar com a engenharia da KMEE?
Tem dúvida específica sobre fluxo de auth, multi-tenant, integração com gateway? Marque uma conversa técnica.