1 / 10
🤖 Claude Code · Guia Técnico

Construindo Lojas Virtuais
com Inteligência Artificial

Infra, bancos de dados, frameworks, linguagens e gateways de pagamento — tudo que você precisa saber para criar um e-commerce moderno com o auxílio do Claude Code.

🐳 Docker Swarm 🗄️ PostgreSQL ▲ Next.js 💳 PIX / Stripe 🔒 Segurança 🤖 Claude Code

Por que usar Claude Code para montar sua loja?

Um agente de IA que lê, edita e executa — diretamente no terminal do seu projeto.

Velocidade 10×

Gera estrutura completa, APIs, schemas e componentes em segundos — código funcional, sem placeholders vagos.

🔒

Segurança nativa

AES-256-GCM, validação de input, proteção de rotas, tokens nunca no frontend — OWASP por padrão.

🗂️

Contexto completo

Lê todos os arquivos do projeto. Decisões coerentes, sem soluções genéricas que quebram no seu ambiente.

🐳

Deploy automático

Gera Dockerfile, docker-compose Swarm, labels Traefik e scripts de deploy prontos para produção.

🔗

Integrações reais

Webhooks idempotentes, gateways de pagamento, SMTP, APIs de terceiros — com tratamento completo de erro.

♻️

Iteração contínua

Corrija bugs, adicione features e refatore com um prompt. O agente mantém consistência ao longo do projeto.

Qual infraestrutura usar?

A escolha impacta custo, escalabilidade e manutenção. Três cenários principais:

🖥️

VPS / Servidor Dedicado

Controle total, custo previsível. Ideal para lojas de médio porte. Use Docker Swarm para orquestração simples.

Custo baixoControle totalManutenção manual
☁️

Cloud Gerenciada

AWS, GCP ou Azure com ECS/GKE. Escalabilidade automática para picos de tráfego (Black Friday).

Auto-scaleAlta disponibilidadeCusto variável

Edge / Serverless

Vercel, Railway ou Cloudflare Workers. Ideal para MVPs Next.js e lojas em validação.

Zero manutençãoDeploy simplesCold starts
🔀

Reverse Proxy — Traefik

Roteia requisições, emite SSL via Let's Encrypt automaticamente e faz load balancing. Integração nativa com Docker Swarm via labels de deploy.

🗃️

Storage + CDN + E-mail

Imagens de produtos no S3 ou Cloudflare R2, assets em CDN, e-mail transacional via SMTP próprio ou Resend/SendGrid com alta deliverabilidade.

Por que usar Docker?

Resolve o clássico "funciona na minha máquina" — ambiente idêntico em dev, staging e produção.

1

Ambiente 100% reproduzível

Mesma versão de Node, PostgreSQL, Redis e dependências em todos os ambientes. Sem surpresas no deploy.

2

Portabilidade total entre ambientes

O mesmo container roda na máquina do dev, no staging e em produção. Migrar de provedor de VPS leva minutos, sem reconfigurar nada.

3

Escalar horizontalmente

docker service scale loja_app=5 — 5 réplicas sem alterar uma linha de código.

4

Rollback instantâneo

Cada versão é uma imagem imutável. Reverter em segundos: docker service rollback loja_app.

5

Isolamento e segurança

Banco não expõe porta ao mundo. Cada serviço tem apenas as permissões necessárias na rede interna.

# Dockerfile multi-stage — Next.js
FROM node:20-alpine AS deps
RUN apk add --no-cache openssl
COPY package*.json ./
RUN npm ci --legacy-peer-deps

FROM node:20-alpine AS builder
RUN npx prisma generate && npm run build

FROM node:20-alpine AS runner
COPY --from=builder /app/.next/standalone ./
CMD ["node", "server.js"]
# docker-compose.yml — Swarm
services:
  app:
    networks: [network_public, internal]
    deploy:
      replicas: 2
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.loja.rule=Host(`loja.com`)"
        - "traefik.http.routers.loja.tls.certresolver=letsencrypt"
  db:
    image: postgres:16
    networks: [internal]

💡 Docker Swarm vs Kubernetes: Para a maioria das lojas, Swarm oferece 80% dos benefícios do K8s com 20% da complexidade. Migre para K8s apenas com múltiplas regiões ou times grandes de infra.

Tipos de Banco de Dados

Lojas virtuais precisam de banco relacional, cache rápido e busca eficiente.

🐘

PostgreSQL — Principal

Pedidos, clientes, produtos, pagamentos. Transações ACID críticas para e-commerce. JSON nativo, full-text search. ORM: Prisma ou Drizzle.

ACIDTransaçõesJSON nativo
🔴

Redis — Cache e filas

Sessões, carrinho temporário, rate limiting, filas BullMQ. Latência sub-milissegundo. Essencial em picos de tráfego como Black Friday.

CacheSessõesFilas BullMQ
🐬

MySQL / MariaDB

Padrão para stacks PHP, WooCommerce e Magento. Amplamente suportado, replicação simples, ORM Eloquent (Laravel) ou Doctrine integrados nativamente.

LaravelWordPressReplicação
🔍

Typesense — Busca

Busca de produtos com filtros, facets e typo-tolerance. Mais simples que Elasticsearch. Sincronize com o PostgreSQL principal via hook.

Full-textFacetsTypo-safe

💡 Regra geral: comece com PostgreSQL + Redis. Adicione MongoDB se o catálogo tiver atributos muito variáveis entre categorias. Adicione Typesense quando a busca simples não atender mais a experiência do usuário.

Frameworks e Linguagens

Cada linguagem tem suas forças para e-commerce — escolha conforme o time e o contexto.

🟨

TypeScript / Next.js

⭐ Recomendado para a maioria

Full-stack com uma linguagem. SSR nativo, App Router, API Routes, Prisma ORM type-safe. Ecossistema npm enorme para integrações.

Next.js 14RemixtRPCPrisma
🐘

PHP / Laravel

Ecossistema maduro para e-commerce

Laravel + Filament Admin completo sem esforço. Livewire para UI reativa. Horizon + Queues para jobs assíncronos de pedido.

Laravel 11LivewireFilament
🐍

Python / Django

IA, ML e data science integrados

Django + Saleor para e-commerce completo. FastAPI para microserviços. Integração natural com ML para recomendação de produtos.

DjangoFastAPISaleor
🐹

Go

APIs críticas de alta performance

Checkout e inventory de alto volume. Binários pequenos, startup ultra-rápido. Goroutines para processar webhooks concorrentemente.

Go FiberChiGORM

Gateways de Pagamento

Escolha conforme métodos de pagamento necessários, taxas e público-alvo.

Gateway BRPIXBoletoCartão
Asaas
PagSeguro
Mercado Pago
Efí Bank
Pagar.me
Iugu

🌎 Internacionais

Stripe — melhor DXPayPalAdyen — enterprise

⚠️ Idempotência obrigatória: salve o ID do evento e verifique antes de processar. Responda HTTP 200 imediatamente — processe em background para evitar timeout.

Fluxo PIX com fallback duplo

Frontend — Checkout
↓ POST /api/checkout
Backend → Cria cobrança PIX
↓ API Asaas / Efí / Mercado Pago
QR Code + Copia e Cola
Polling 5s (fallback)
Webhook (principal)
↓ Ambos são idempotentes
✅ Ativa plano + envia e-mail

Stack ideal para lojas virtuais

Maturidade de ecossistema + produtividade + facilidade de operação em produção.

🎨

Frontend — Next.js 14 + Tailwind CSS

App Router, Server Components, SSR nativo. Framer Motion para micro-interações.

⚙️

Backend — Next.js API Routes

Monorepo full-stack. Para filas pesadas: microserviço Node.js com BullMQ + Redis.

🗄️

Banco — PostgreSQL 16 + Prisma ORM

Schema type-safe, migrations versionadas, Prisma Studio como GUI de dev.

🔐

Auth — NextAuth.js com roles

Roles ADMIN e CUSTOMER via JWT. Middleware protegendo todas as rotas sensíveis.

💳

Pagamento — Asaas (BR) + Stripe (Intl)

PIX, boleto e cartão no Brasil. Webhooks idempotentes. Stripe para clientes internacionais.

🐳

Deploy — Docker Swarm + Traefik

Stack declarativa. SSL automático via Let's Encrypt. Portainer para gestão visual.

🏗️ Arquitetura de produção

Internet + Cloudflare CDN
Traefik (SSL + Roteamento)
Next.js réplica 1
Next.js réplica 2
PostgreSQL
Redis

🔒 Segurança obrigatória

  • Credenciais criptografadas AES-256-GCM no banco
  • Docker Secrets para DATABASE_URL e chaves sensíveis
  • API Keys de pagamento apenas no backend
  • Rate limiting no checkout para prevenir fraude
  • Webhook validado por token de autenticação

Cada componente da stack explicado

Por que cada escolha foi feita e o que você ganha com ela na prática.

Next.js 14 + Tailwind CSS

Frontend
App Router: layouts aninhados, loading.tsx e error.tsx nativos — UX de SPA sem escrever roteamento manual.
Server Components: renderizam no servidor, zero JS extra no cliente — SEO perfeito e Time to First Byte reduzido.
SSR / SSG / ISR: páginas de produto em cache estático, checkout em SSR, carrinho no cliente.
Tailwind + shadcn/ui: classes utilitárias com purge automático; componentes Radix acessíveis sem lock-in de biblioteca.
⚙️

Next.js API Routes

Backend
Route Handlers: app/api/rota/route.ts — GET/POST/PATCH por arquivo, sem configurar Express.
Middleware: middleware.ts protege rotas antes de renderizar — autenticação centralizada em um lugar.
Zod: schemas tipados validam body, query e params — erros descritivos, sem if/else de validação manual.
Edge Runtime: handlers de rate limit e auth check executam na CDN — latência abaixo de 10 ms globalmente.
🗄️

PostgreSQL 16 + Prisma ORM

Banco de Dados
schema.prisma: fonte única de verdade — modelos, relações e tipos TypeScript gerados automaticamente via prisma generate.
Migrations: prisma migrate deploy versionado em git — rollback rastreável de qualquer mudança de schema.
Prisma Client: queries 100% tipadas com autocomplete — sem SQL manual, erros de tipo em compile time.
PgBouncer: pool de conexões — evita "too many clients" com múltiplas réplicas em pico de tráfego.
🔐

NextAuth.js com Roles

Autenticação
Credentials Provider: login com e-mail e senha verificado no banco — sem depender de OAuth de terceiros.
JWT com roles: role: "ADMIN" | "CUSTOMER" embutido no token — sem query extra a cada requisição.
Middleware de proteção: verifica role antes de renderizar — /admin bloqueado automaticamente para não-admins.
bcrypt: senhas com salt automático e custo configurável — resistente a ataques de dicionário e rainbow tables.
💳

Asaas (BR) + Stripe (Intl)

Pagamentos
PIX via Asaas: cria cobrança → QR Code → polling 5 s + webhook PAYMENT_RECEIVED como canal redundante.
Idempotência: salva event.id na tabela WebhookEvent — duplicatas ignoradas sem efeito colateral.
Webhook auth: valida o header asaas-access-token — rejeita payloads não autorizados antes de processar.
Credenciais criptografadas: API keys com AES-256-GCM no banco — nunca em .env, gerenciadas pelo painel /admin.
🐳

Docker Swarm + Traefik

Deploy & Infra
Overlay networks: network_public para Traefik rotear; internal isola o banco sem expor porta ao mundo.
Docker Secrets: db_password e nextauth_secret injetados em runtime — nunca aparecem em logs de container.
Traefik labels: SSL Let's Encrypt automático e roteamento por Host diretamente nas labels do docker-compose, sem config extra.
Health checks + Portainer: Swarm reinicia containers com falha automaticamente; Portainer oferece UI web para gerenciar sem SSH.

Como o Claude Code constrói sua loja

Com um arquivo de especificação detalhado, o Claude gera código funcional — não boilerplates genéricos.

1

Escreva a especificação (YAML ou Markdown)

Descreva rotas, integrações, regras de negócio, design e infra. Quanto mais detalhado, melhor o resultado.

2

Claude lê e planeja

Analisa o spec completo, identifica dependências entre módulos e monta um plano coerente antes de escrever qualquer código.

3

Geração de código funcional

Schema Prisma, API routes, componentes, Dockerfile multi-stage, docker-compose Swarm, migrations e seed — tudo de uma vez, sem lacunas.

4

Deploy automatizado na VPS

Cria script de deploy, configura labels Traefik, verifica redes overlay e executa docker stack deploy diretamente.

5

Iteração rápida

Erros de build, ajustes de UI, novas integrações — tudo via prompt em linguagem natural. Contexto preservado.

## Spec de exemplo (plano_final.yaml)

## Design
- Mobile-first, cores #6C5CE7
- Checkout com stepper 4 etapas

## Rotas
- / → home com planos do banco
- /checkout → PIX com polling
- /dashboard → credenciais do cliente
- /admin → CRUD completo

## Integrações
- Asaas: PIX + webhook idempotente
- SMTP: credenciais ao cliente

## Segurança
- AES-256-GCM no banco
- Nada sensível em .env

## Stack
- Next.js 14 + Prisma + PostgreSQL
- Docker Swarm + Traefik
10×
mais rápido que
desenvolvimento manual
0
placeholders ou
código incompleto

Antes de ir ao ar

Itens essenciais para uma loja virtual em produção com Claude Code.

🔒 Segurança

  • HTTPS em todas as rotas
  • Headers CSP, HSTS, X-Frame
  • Validação no backend
  • Rate limiting no checkout
  • Tokens webhook validados
  • Secrets no Docker Swarm
  • Logs sem dados sensíveis

⚡ Performance

  • CDN para imagens e assets
  • Cache Redis para sessões
  • Lazy loading de imagens
  • Bundle JS < 200 KB inicial
  • Core Web Vitals no verde
  • Índices corretos no banco
  • PgBouncer para pooling

🛡️ Confiabilidade

  • Backup automático do banco
  • Health checks nos containers
  • Alertas de erro (Sentry)
  • Webhook idempotente
  • Rollback testado em staging
  • Monitoramento de uptime
  • Disaster recovery documentado

🚀 Resultado com Claude Code: loja completa com checkout PIX, painel admin, provisionamento automático, Dockerfile multi-stage e deploy em Docker Swarm — gerada em uma única sessão de trabalho. Especifique bem, o Claude entrega.

CMS prontos vs Código 100% próprio com Claude Code

Onde cada plataforma se encaixa — e quando construir do zero é a melhor decisão.

Plataforma Custo mensal Personalização Performance Vendor lock-in Escalabilidade Integrações Claude Code 100% próprio
WordPress + WooCommerce $15–80/mês Média (plugins) Baixa (PHP pesado) Baixo Médio Muitos plugins Controle total, arquitetura limpa, sem plugins conflitantes
Shopify $39–399/mês + taxas Limitada (Liquid) Boa (CDN Fastly) Alto Alta App Store Sem taxas por transação, lógica de negócio 100% customizável
VTEX % do GMV (≥ $2k/mês) Alta Boa Alto Alta Nativa BR Custo zero de plataforma, não paga % sobre vendas
Magento / Adobe Commerce $0 (OSS) a $50k+/ano Alta Média Médio Alta Complexo Sem curva de aprendizado da plataforma, stack moderno
Wix / Squarespace $17–49/mês Muito baixa Média Total Baixa Limitadas Sem limite de SKUs, lógica de frete e preço customizável
Nuvemshop / Tray R$99–699/mês + taxas Baixa–Média Média Alto Médio Nativa BR UX 100% personalizada, sem templates engessados
🏪

Use um CMS quando…

Você precisa ir ao ar em dias, tem orçamento limitado de dev, ou o negócio ainda está validando mercado. WordPress e Shopify entregam rápido.

⚖️

Cuidado com plataformas SaaS

Taxas sobre GMV, limitações de checkout, impossibilidade de hospedar fora da plataforma e dependência total do roadmap do fornecedor.

🤖

Código próprio com Claude Code quando…

Você quer controle total, regras de negócio complexas, integrações únicas (ERP, CRM, WhatsApp), sem pagar taxa por venda e sem vendor lock-in.

← → para navegar · clique no slide na lateral