Pular para o conteúdo

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.

Documentação técnica

  1. 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 router
    • middleware.ts
    • CMS
    • pagamentos
    • sitemap/robots
    • Vercel deploy

  2. 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.

    • ProductCard
    • CartDrawer
    • ProductGallery
    • ProductFilters
    • GlobalHeader
    • Footer

  3. Camada 2 - React Providers & Hooks

    Camada de cola entre os clientes headless e a UI. CartProvider, WishlistProvider, SupabaseAuthProvider, hooks de listagem e auth.

    • CartProvider
    • WishlistProvider
    • SupabaseAuthProvider
    • useCart
    • useWishlist
    • useProductsPage

  4. Camada 1 - Clientes Headless

    Sem React, sem Next.js. Classes puras com auth/logger/fetcher injetáveis. Roda em qualquer runtime (Node, edge, worker).

    • OdooHttpClient
    • ProductService
    • CartService
    • SalesService
    • AddressService

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.

  1. 1

    Cliente abre o storefront

    UI

    Next.js 15 SSR. Página de listagem busca produtos no Elasticsearch via ProductService (server-side).

  2. 2

    Cliente busca um produto

    UI -> Headless

    Busca facetada no Elasticsearch. Resultados com collapse por modelo, brands, categorias, related products via Levenshtein.

  3. 3

    Cliente faz login

    Auth

    SupabaseAuthProvider abre fluxo Supabase. Token volta pro client + server. CartProvider sincroniza carrinho local com Odoo.

  4. 4

    Cliente adiciona ao carrinho

    React -> Headless -> Odoo

    useCart() chama CartService.addToCart(). Token Supabase atravessa pro Odoo via OdooHttpClient. Estado atualiza no React.

  5. 5

    Checkout

    Headless -> Odoo

    AddressService busca endereços. DeliveryCarriersService calcula fretes. SalesService confirma pedido no Odoo. Fiscal nativo (NF-e/NFS-e).

  6. 6

    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.

Agendar diagnóstico grátis Ver os 8 packages