01 / 16
Ambiso
Documentação viva · 2026-06-24

Arquitetura
do
Workspace

A jornada completa — do negócio à stack técnica — em um só lugar. Deslize para baixo.

2motores de receita
5apps · 1 worker
50+endpoints
deslize ↓
02 / 16
O modelo de negócio

Dois motores, um workspace

A. E-commerce

A marca AMBISO — camisetas básica/oversized, loja Shopify, Pix, frete Sul/Sudeste. Aposta de longo prazo, hoje movida a conteúdo orgânico (TikTok-first).

B. DTF local

O serviço de estampa sob demanda (uniformes, eventos, brindes na região). É o motor de receita real — vendas por WhatsApp + draft order.

"A marca é o experimento financiado pelo serviço — não o contrário."

03 / 16
Visão geral

O mapa da stack

1
Shopify (tema Liquid) — a loja `ambiso.com.br`, vitrine + checkout.
2
Cloudflare Worker — o hub backend que conecta tudo (frete, CAPI, estoque, dashboard).
3
Cloudflare Pages — dashboard, guia UGC, orçamentos DTF e este deck.
4
KV + R2 — estoque/cache/sessões e imagens de produto.
5
Integrações — Frenet, Meta CAPI, GA4, Google Ads, GMC, Clarity.
04 / 16
Jornada 1 · passo a passo

Compra e-commerce

1
Cliente navega a loja (tema Shopify), vê produto.
2
PDP cota frete → POST /shipping no worker (Frenet + cache).
3
Checkout nativo Shopify, paga via Pix.
4
webhook/checkout → CAPI InitiateCheckout.
5
webhook/order-paid → baixa estoque KV + envia CAPI Purchase.
6
Dashboard reflete o pedido; NF-e + Frenet no fulfillment.
05 / 16
Jornada 2 · passo a passo

Venda local DTF

1
Cliente chega por Google Meu Negócio / WhatsApp.
2
Operador gera Draft Order no Shopify + manda orçamento.
3
Cliente paga Pix pelo link do draft.
4
Worker detecta source_name = shopify_draft_order → pula CAPI (não é tráfego pago).
5
Orçamento mobile (`orcamentos.ambiso.com.br`) formaliza a proposta.
6
Impressão DTF + entrega — o motor de receita real.
06 / 16
O cérebro

O worker unificado

Um único Cloudflare Worker roteia tudo: index.js + 8 handlers, 50+ endpoints, webhooks validados por HMAC.

handlers-webhooks

Pedido pago, checkout, cancelamento → CAPI + estoque.

handlers-frete

Carrier Service Shopify + Frenet SOAP + regras Ambiso.

handlers-kpi

Dashboard: Shopify + Meta + GA4 + Google Ads.

handlers-estoque

Sync MP↔Shopify (GraphQL) + R2 + auditoria.

07 / 16
Fluxo · frete

Cotação em ~64 ms

O gargalo é o SOAP da Frenet (~5,6 s). Um cache de isolate (30 min, por CEP+peso) derruba o hit para dezenas de ms — zero write em KV.

  • POST /shipping — Carrier Service oficial, chamado pela PDP/carrinho.
  • Frete grátis para Sul + Sudeste (7 estados), sem mínimo.
  • Retirada local CEP 875xx = R$0 (LOCAL_PICKUP).
  • Frenet é o único provedor (Melhor Envio aposentado).
08 / 16
Fluxo · Meta CAPI

Conversões sem ruído

Eventos server-side para o Pixel Meta — com filtros que evitam conversão falsa.

Purchase InitiateCheckout ViewContent
  • Skip venda local — draft order não conta como Purchase.
  • Skip amostra grátis — tag SELLER_FUND_FREE_SAMPLE do TikTok não infla ROAS.
  • Throttle de ViewContent (1/min por IP+coleção).
09 / 16
Fluxo · estoque

KV é a fonte da verdade

1
MP-* no KV = modelo·cor·tamanho com quantidade real.
2
Sync para Shopify via GraphQL, por inventory_item_id (nunca variant_id).
3
CRON 9h e 21h (ou /api/sync-shopify).
4
Dirty-check obrigatório antes de escrever (free tier: 1000 writes/dia).
10 / 16
Operação

O dashboard

SPA em ambiso-dashboard-unificado.pages.dev, login por PIN de 4 dígitos.

  • KPIs agregados — Shopify + Meta + GA4 + Google Ads.
  • auditOrderForKpi — exclui teste, refund, venda local, amostra.
  • evaluateCampaign — D1–D3 lê, D4+ troca criativo; nunca pausa.
  • Share links com PIN/TTL para visão somente-leitura.
11 / 16
Conteúdo

Sistema UGC orgânico

Guia em ugc.ambiso.com.br (protegido por PIN), TikTok-first. Três abas:

Referências

91 posts curados — tendências + estética Ambiso.

Conteúdo

Calendário + heróis + roteiros prontos (Seg/Qua/Sex).

Ideias

39 ideias estruturadas para gravar.

Métrica real

Vídeos publicados/semana — não mais infra.

12 / 16
Pipeline · lançamento

Nova estampa → loja

1
Selecionar + otimizar imagens (ranking → WebP 2000²).
2
Cadastrar no Shopify (8 variantes: 4 tam × 2 cores).
3
Sync KV → Shopify + checklist de metafields/descrição/tags.
4
GMC obrigatório — subir feed; categoria por ID numérico.
5
auditoria-feed-gmc.py = 0 erros → commit.
13 / 16
Atualizado · 2026-06-24

Ferramentas de dev (MCP)

Servidores MCP versionados em .mcp.json turbinam o trabalho assistido.

shopify-dev novo

Schema GraphQL validado + docs + validação de Liquid/tema. Caça campo inventado antes de tocar a loja.

chrome-devtools

DOM/console/network no Chrome logado — auditorias e debug.

yt-dlp

Baixar/otimizar mídia de redes para o UGC.

Guard

Editar `.mcp.json` é bloqueado pelo classifier — operador faz manual.

14 / 16
Onde tudo mora

Mapa de deploys

Serviço
Host
Loja
ambiso.com.br
Worker (hub)
…workers.dev
Dashboard
dashboard-unificado.pages.dev
Guia UGC
ugc.ambiso.com.br
Orçamentos
orcamentos.ambiso.com.br
Este deck
ambiso-arquitetura.pages.dev
15 / 16
O que mantém de pé

Disciplina & lições

  • Hierarquia de verdade — filesystem real > CONTEXTO-MASTER > copilot-instructions.
  • inventory_item_id ≠ variant_id — a confusão zerou syncs.
  • HMAC sempre — todo webhook é validado.
  • KV discipline — dirty-check + TTL obrigatórios.
  • GMC — categoria por ID numérico, imagem JPEG.
16 / 16
Ambiso
O que importa

O motor real é
a impressora

A stack é sólida e pronta. O gargalo não é técnico: é volume de DTF local + vídeos orgânicos publicados.

"Infra pronta não vende. Conteúdo postado e impressora ligada, sim."