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

O desenho em uma tela

Cada camada depende só da de baixo. Os sistemas de fora entram pelos clientes headless; o comprador só vê o app.

Diagrama da arquitetura headless do K-Shop Comprador navegador ou celular página pronta no servidor 4 App / Storefront

Next.js 15: rotas, middleware, CMS, pagamentos, SEO

 3 UI

Tailwind + Radix: ProductCard, CartDrawer, filtros, header

 2 Providers e hooks

CartProvider, SupabaseAuthProvider, useCart, useProductsPage

 1 Clientes headless

classes puras, sem React: OdooHttpClient, ProductService, CartService

 Odoo

catálogo, pedidos, clientes, fiscal, estoque, frete

 Elasticsearch

listagens, busca com filtros, relacionados

 Supabase

login do comprador, ligado ao cliente no Odoo

 carrinho, checkout, pedido busca facetada token do comprador atravessa até o Odoo
Diagrama da arquitetura headless do K-Shop

  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 em qualquer host Node ou container.

    • app router
    • middleware.ts
    • CMS
    • pagamentos
    • sitemap/robots
    • deploy agnóstico

  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