Integração capstone: demo técnico‑de produto e “passaporte do App”

1. O que é o “passaporte do App” e por que você precisa dele

O passaporte do App é um documento compacto, porém denso (geralmente 1–2 páginas em Markdown ou uma seção no README), que dá a qualquer pessoa uma visão rápida do seu ChatGPT App: como ele é estruturado, quais são suas limitações, como ele gera receita e como você o opera em produção.

Não é um folheto de marketing. Ele não fala das “tecnologias de IA mais inovadoras”, e sim de coisas muito concretas:

• onde passa a fronteira entre o ChatGPT, o seu widget, o servidor MCP, os agentes e o ACP/Stripe;
• quais PII você armazena, como funciona o OAuth/scopes e a rotação de segredos;
• quais são seus SLO de latência e disponibilidade, quais dashboards e alertas existem;
• quanto custa em média um fluxo bem‑sucedido e como você cobra por ele;
• quais incidentes típicos já estão documentados e onde estão os runbooks;
• o que você planeja fazer com esse App nos próximos meses.

Você pode pensar no passaporte como um agregador de links e descrições de alto nível, que muda com menos frequência do que o código, mas mais frequentemente do que a “apresentação oficial para investidores”.

Para você, como desenvolvedor de ChatGPT App, o passaporte também é um checklist de maturidade. Se alguma seção estiver vazia (“e os SLO nós meio que não descrevemos…”), isso é um bom sinal vermelho: significa que não falta só documentação, mas também a prática em si.

2. Estrutura básica do passaporte do GiftGenius

Para o GiftGenius, faz sentido adotar a seguinte estrutura (você pode ajustá‑la levemente para o seu App, mas a ideia geral permanece).

Vamos apresentar em uma pequena tabela quem lê o quê e para quê:

A seguir, vamos detalhar cada um desses blocos e, em paralelo, rascunhar um PASSPORT.md real para o GiftGenius.

3. Arquitetura: como mostrar todo o stack em uma única figura

A seção de arquitetura é o coração do passaporte. Não é necessário desenhar um diagrama UML com 200 retângulos. O importante é mostrar camadas e fluxos: do usuário no ChatGPT até o seu BD e o serviço de pagamento. Para um ChatGPT App com Apps SDK e MCP, esse caminho é padrão.

Um formato conveniente é um diagrama Mermaid direto dentro do PASSPORT.md. Por exemplo, para o GiftGenius:

flowchart TD
  U[User in ChatGPT] --> C[ChatGPT + GPT-5]
  C --> W[GiftGenius Widget
Next.js + Apps SDK]
  W --> MCP[MCP Server
giftgenius-mcp]
  MCP --> A[Agent: GiftPlanner]
  A --> DB[(Postgres: products,gifts)]
  A --> ACP[ACP / Stripe]
  ACP --> ORD[(Orders)]

No texto abaixo do diagrama, você descreve o cenário principal:

O usuário no chat descreve o destinatário do presente. O modelo decide chamar o tool suggest_gifts no servidor MCP. O agente pode, além disso, ler catálogos como recursos e executar vários tools. Depois, ao escolher um presente, é criada uma sessão ACP no Stripe, o checkout passa por webhooks e o resultado é salvo no BD.

É bom se você já mencionar as tecnologias: Next.js 16 + Apps SDK, servidor MCP em Node/Python, PostgreSQL, Redis para cache, Stripe como meio de pagamento.

Você pode adicionar à seção de arquitetura um pequeno trecho técnico para mostrar como os tijolos arquiteturais aparecem no código. Por exemplo, um pedaço de rota do Next.js que repassa requestId e userId ao cliente MCP:

// app/api/suggest-gifts/route.ts
import { mcpClient } from "@/lib/mcpClient";

export async function POST(req: Request) {
  const { occasion, budget } = await req.json();
  const requestId = crypto.randomUUID();      // trace para logs
  const userId = req.headers.get("x-user-id") ?? "anonymous";

  const result = await mcpClient.callTool("suggest_gifts", {
    occasion, budget, requestId, userId,
  });

  return Response.json({ requestId, result });
}

Esse trecho ajuda a conectar a setinha abstrata no diagrama “Widget → MCP” com o código real.

4. Segurança & privacidade: o que exatamente precisa ser registrado

Segurança no passaporte não é “usamos HTTPS e backend em TypeScript, então está tudo certo”. São necessárias respostas concretas para as perguntas de segurança, compliance e jurídico.

Para o GiftGenius, vale descrever brevemente:

Qual é o modelo de autenticação e autorização:
para cenários de comércio é usado OAuth 2.1 com PKCE via MCP Auth Server; o token é vinculado a user_id e tenant_id, todas as chamadas de tool relacionadas ao checkout exigem o scope commerce.checkout.

Quais dados são PII e como você lida com eles.
Por exemplo: e‑mail e nome — PII, preferências de presentes — dados pseudo‑anônimos; registramos apenas o e‑mail com hash, endereço de entrega não é armazenado, apenas repassado ao Stripe e aos webhooks.

Como funcionam retenção e exclusão:
logs de ferramentas são mantidos por 30 dias, eventos de commerce — 1 ano; a pedido do usuário, podemos excluir seus pedidos e os eventos analíticos relacionados.

Como você gerencia segredos:
descreva brevemente onde ficam o OpenAI API key, o Stripe secret, o OAuth client secret (por exemplo, em um managed secret store), com que frequência você os rotaciona e como isso é testado no staging.

No passaporte, você pode incluir um pequeno trecho técnico para demonstrar o princípio do “menor privilégio”.

// config/scopes.ts
export const TOOL_SCOPES = {
  suggest_gifts: ["read:products"],
  get_gift_details: ["read:products"],
  create_checkout_session: ["read:products", "write:orders", "stripe:checkout"],
} as const;

Depois, na descrição do tool e do MCP‑auth, você referencia esses mesmos scopes. Isso deixa de ser apenas palavras sobre “least privilege” e vira um contrato concreto.

5. Observabilidade e SLO: para enxergar como o App vive

O próximo bloco do passaporte é sobre observabilidade: como você entende que o App está vivo e saudável. Aqui se unem logs estruturados, métricas, SLO e links para dashboards.

Para o GiftGenius, faz sentido descrever:

SLO principais.
Por exemplo: disponibilidade do MCP ≥ 99.5%, latência p95 para suggest_gifts < 5 segundos, success‑rate do checkout ≥ 99%.

Onde acompanhar esses SLO.
Nome e URL do dashboard no Grafana/Datadog/… (no passaporte você pode indicar apenas “Dashboard: GiftGenius / SLO”).

Formato dos logs estruturados.
No módulo anterior sobre observabilidade, você já pensou nos campos request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. No passaporte é útil trazer um exemplo JSON (pequeno), mas vamos além — definimos um tipo em TypeScript, que é usado também no código.

// lib/logging.ts
export type ToolInvocationLog = {
  level: "info" | "error";
  timestamp: string;
  requestId: string;
  userId?: string;
  toolName: string;
  tokensIn?: number;
  tokensOut?: number;
  costEstimateUsd?: number;
};

E a função helper:

export function logToolInvocation(event: ToolInvocationLog) {
  console.log(JSON.stringify({ type: "tool_invocation", ...event }));
}

Agora esse tipo vira uma ponte entre o código e o passaporte: na seção de Observabilidade você escreve que todas as chamadas de tool são registradas no formato ToolInvocationLog e anexa um link para o dashboard que agrega esses registros.

Você pode adicionar um esquema textual curto:

Log de evento → armazenamento de logs → dashboards de SLO → alertas → incidente/Runbook.

6. Economia & métricas de produto: dinheiro e comportamento do usuário

Aqui você conecta tudo o que foi feito no bloco anterior sobre economia (M19): métricas de custo, pricing e analytics de produto.

Para o GiftGenius, vale consolidar no passaporte:

A unit economics do cenário principal (algo como “economia de uma tarefa concluída”).
Por exemplo: “Média de cost_per_successful_task (seleção de presente com pagamento bem‑sucedido) = $0.13 (LLM + infra). Receita média por task = $0.80 (CPA de parceiros).”

O modelo principal de monetização.
Breve: “Seleção básica gratuita sem compra; monetização via CPA por ida à loja parceira + assinatura premium opcional com filtros avançados e histórico de presentes”.

Métricas de produto principais.
Por exemplo: activation‑rate = proporção de usuários que tiveram ao menos um workflow_completed; repeat‑rate = proporção de usuários que voltaram pelo menos uma vez no mês; conversão de workflow_completed → checkout_success.

Experimentos.
Lista de A/B ativos: “Modelo A (caro) vs modelo B (barato)”, “Wizard longo vs inline rápido”. Para cada um, você mantém experiment_id, variantes, métricas alvo (conversão, cost_per_task, quality‑score).

Isso também pode aparecer no código, para que o passaporte não fique só na teoria — por exemplo, por meio de um helper unificado para eventos analíticos:

// lib/analytics.ts
export function trackEvent(
  name: string,
  payload: Record<string, unknown>,
) {
  console.log(JSON.stringify({
    type: "analytics",
    name,
    ts: new Date().toISOString(),
    ...payload,
  }));
}

E a chamada quando o workflow termina com sucesso:

trackEvent("workflow_completed", {
  userId,
  requestId,
  experimentId: "model_ab_01",
  variant: "A",
  costUsd: 0.13,
  checkoutSuccess: true,
});

No passaporte, você descreve quais eventos são chave e quais KPIs dependem deles. O código é a prova de que você realmente mede algo, e não apenas promete.

Mas métricas e economia só fazem sentido quando o App funciona de forma estável em produção. Por isso, na próxima seção veremos como registrar no passaporte o lado operacional do GiftGenius: incidentes, on‑call e runbooks.

7. Operações & incidentes: como você vai conviver com o App em produção

Esta seção é sobre como você reage quando as coisas não saem como planejado.

Para o GiftGenius, faz sentido listar no passaporte pelo menos dois incidentes típicos:

Problemas de pagamento.
Por exemplo: queda do success‑rate do checkout abaixo do SLO, erros em massa nos webhooks do Stripe. No passaporte você aponta que existe o runbook “Checkout Failures”, onde estão descritos sintomas, onde olhar (dashboard de erros, logs do endpoint de webhook), passos rápidos de mitigação (medidas temporárias: desabilitar um feature flag problemático, redirecionar parte do tráfego para o sandbox ou oferecer temporariamente apenas gift cards) e follow‑up (post‑mortem, adição de novos alertas).

Problemas com MCP/LLM.
Por exemplo: aumento da latência p95 para suggest_gifts para 9 segundos ou erro “Error talking to app” para uma grande porcentagem de requisições. Aqui há um runbook separado: checar o status da OpenAI, do túnel/Vercel, health‑check do MCP, alternar para o modo degradado em que o agente tenta responder sem acesso ao catálogo (ideias gerais do modelo, sem commerce).

Nesta mesma seção, você descreve brevemente o calendário operacional: com que frequência revê os SLO, faz o cost‑review, verifica os logs de segurança e rotaciona segredos.

Também é possível indicar quem está de on‑call (mesmo que seja só você) e em qual canal do Slack ou e‑mail os alertas chegam.

8. Roadmap & riscos: um olhar honesto para frente

O bloco final do passaporte é sobre o futuro. Não precisa escrever um romance. Bastam 3–5 passos reais de evolução do App e algumas limitações conhecidas.

Para o GiftGenius, isso pode ser algo assim:

• lançar avaliações com LLM (LLM‑evals) para a qualidade das recomendações, a fim de conectar qualidade à conversão;
• adicionar mais um locale e testar descrições de ferramentas localizadas;
• experimento com modelos mais baratos em parte do tráfego;
• melhorar a resiliência a falhas do Stripe (tratar webhooks e confirmações atrasadas de forma mais robusta);
• preparar a migração para a nova versão do Apps SDK ou do MCP (com versionamento de contratos de ferramentas).

Restrições: limites (caps) de API, limitações da UI do ChatGPT (por exemplo, limite no número de cards no resultado), pontos fracos da arquitetura atual (BD em uma única região, ausência de hot standby do MCP etc.).

Plano de experimentos: quais hipóteses você pretende testar em pricing/UX/modelos e por quais métricas tomará decisões.

9. Onde o passaporte deve viver e como atualizá‑lo

Na prática, o formato mais conveniente é o PASSPORT.md na raiz do repositório do GiftGenius ou na pasta docs/, além de uma cópia/link no seu sistema de documentação (Confluence, Notion etc.).

Ele deve ser leve o suficiente para ser lido em 10–15 minutos e denso o suficiente para permitir responder às perguntas:

• “o que é esse App, afinal, e como ele é estruturado?”
• “o que acontece se o X cair?”
• “quanto nos custa um usuário?”
• “quais riscos mais nos preocupam agora?”

Vale atualizar o passaporte quando houver mudanças em:

• fronteiras arquiteturais (novo serviço, novo meio de pagamento, migração para outro stack);
• SLO chave ou políticas de segurança (por exemplo, outra retenção);
• modelo de monetização;
• incidentes significativos e conclusões de post‑mortems.

Pequenas mudanças de código não exigem alteração imediata do passaporte, caso contrário ele vira apenas mais um documento defasado.

O passaporte é, essencialmente, o concentrado de tudo o que você sabe sobre seu App. O passo lógico seguinte é aprender a usá‑lo para contar sobre o produto para pessoas de carne e osso: técnicos e negócios.

10. Demo técnico‑de produto: por que são necessárias duas “versões da história”

Quando você apresenta o GiftGenius, quase sempre fala para dois tipos de audiência (às vezes misturados na mesma sala):

• técnicos (CTO, arquitetos, segurança, líderes de desenvolvimento);
• audiência de produto/negócios (CEO, investidores, product managers, marketing).

Para a pessoa técnica, é importante que:

• a arquitetura seja clara, as camadas estejam separadas, e existam pontos de extensão;
• confiabilidade e observabilidade estejam pensadas: logs, tracing, SLO, alertas;
• haja uma história de resiliência: o que acontece se caírem OpenAI, MCP, Stripe;
• como você planeja a evolução (migração de SDK/MCP/modelos).

Para o negócio, outras coisas importam mais:

• qual é a dor do usuário (por exemplo, “procurar um presente leva 40 minutos”);
• como o GiftGenius resolve essa dor dentro do ChatGPT em poucos minutos;
• qual é sua monetização, unit economics e métricas de crescimento;
• se isso reduz o CAC, aumenta a conversão/receita.

Portanto, pense em dois “campos” da mesma história de demo: sinais de produto maduro são mostrados a ambos, mas com ênfases diferentes.

11. Roteiro do demo técnico do GiftGenius (5–7 minutos)

Imagine que você está apresentando o GiftGenius para uma audiência técnica.

Primeiro, um contexto curto.
Literalmente 30 segundos: “O GiftGenius é um ChatGPT App para selecionar presentes com checkout via ACP. Vivemos dentro do ChatGPT, usamos Apps SDK, MCP e um agente para planejar etapas.”

Depois, o slide de arquitetura/trecho do passaporte.
Você abre um diagrama parecido com o que escrevemos no Mermaid e explica onde está a fronteira de responsabilidade do ChatGPT (parte LLM), onde está o seu widget, onde está o MCP e onde está a camada de commerce com o Stripe. Aqui é útil mostrar que todos os tools estão encapsulados no MCP e que o widget é uma camada fina de UI.

Live demo com logs.
Em seguida, você liga o split‑screen: à esquerda — ChatGPT com o GiftGenius; à direita — logs ou MCP Inspector. Faz uma solicitação natural como “selecione um presente para um gamer de até US$ 50”. Durante a execução, você mostra:

• a chamada do tool suggest_gifts com request_id;
• o log estruturado tool_invocation, onde dá para ver tokens, cost_estimate e duration_ms;
• um tool secundário que cria a sessão ACP e gera o pedido.

É ótimo se você puder abrir o dashboard logo em seguida: “aqui está a latência p95 desse cenário nas últimas 24 horas; aqui está o success‑rate do checkout”. É quando a pessoa técnica entende que isso não é um pet project, mas sim um sistema com observabilidade.

Injeção de falhas (opcional, mas muito impactante).
Se você estiver confiante no sistema (ou tiver preparado o cenário), pode desligar temporariamente, digamos, o acesso ao catálogo (BD) e repetir a requisição. Você mostra que:

• o MCP registra corretamente o erro e o alerta dispara;
• o agente muda para um modo degradado e informa honestamente ao usuário que o catálogo está indisponível, mas pode sugerir ideias genéricas;
• o checkout não está disponível nesse modo.

No final — um breve sobre operação e evolução.
Você encerra com um slide do passaporte com SLO, incidentes e roadmap: quais são seus objetivos, como você os monitora, quais incidentes já estão cobertos por runbooks, o que virá na v2 (escalabilidade, novos modelos, novos mercados).

A principal mensagem para a audiência: você não tem apenas uma UI bonita, mas uma plataforma bem pensada, pronta para a vida em produção.

12. Roteiro do demo de produto (visão de negócios)

Agora o mesmo GiftGenius, mas contado como produto.

Comece com a história do usuário.
Por exemplo: “Temos a Kátia; ela precisa escolher um presente para um colega ainda hoje. Normalmente ela gasta 30–40 minutos em sites de lojas.”

Mostre o ChatGPT com o GiftGenius.
Kátia escreve uma frase natural, em vez de clicar em filtros de um marketplace: “escolha um presente para um colega que gosta de jogos de tabuleiro, com orçamento de até US$ 50”. O ChatGPT explica que pode usar o GiftGenius e abre o widget. O GiftGenius pergunta alguns detalhes e mostra uma lista de opções.

Passe para o resultado e o valor.
Mostre os cards dos presentes, a possibilidade de salvar ou ir direto para a compra, o checkout via ACP/Stripe. É importante dizer: “tudo isso leva 3–5 minutos, e no lugar onde o usuário já passa o tempo — no ChatGPT”.

Depois, 1–2 minutos sobre monetização e métricas.
Explique que vocês ganham via CPA ou comissão das lojas, e talvez ofereçam um modo premium para usuários frequentes. Aponte os números do passaporte: quanto custa um cenário bem‑sucedido, qual é a conversão para compra e qual a margem prevista.

Em seguida — um pouco sobre crescimento.
Conte como planejam atrair usuários: por meio do listing na Store do ChatGPT, conteúdo, integrações com parceiros. Mas sempre conecte às métricas de produto: “observamos como a mudança no listing impacta o número de novos app_opened e o activation‑rate; como artigos e vídeos impactam o retention e a proporção de usuários com mais de um workflow_completed”.

Finalize com riscos e plano.
Fale honestamente sobre as limitações atuais (por exemplo, dependência de limites da OpenAI/Stripe, suporte ainda fraco a locales) e mostre o roadmap: quais experimentos e melhorias estão no pipeline.

Se fizer tudo com cuidado, a audiência de negócios verá não apenas “mais um widget de IA”, mas um produto claro, com economia e plano de crescimento.

13. Prática: monte seu passaporte e o demo em torno do GiftGenius

Como prática para esta aula, você pode, no seu repositório do GiftGenius, criar o arquivo PASSPORT.md e preenchê‑lo com pelo menos cinco blocos: arquitetura; segurança; observabilidade/SLO; economia e métricas de produto; incidentes/operações. Assim que você escrever um novo runbook ou alterar um SLO, volte ao passaporte e reflita essa mudança.

Em paralelo, vale escrever um roteiro de demo de 5–7 minutos: nos primeiros 2–3 minutos — o cenário do usuário e o valor; nos 2–3 seguintes — arquitetura e operação (SLO, custo, incidentes). Esse roteiro treina muito bem a habilidade de falar tanto a linguagem do negócio quanto a da técnica, sem cair nem em código seco, nem em marketing vazio.

Esses artefatos não são “papelada para cumprir tabela”, mas a base do demo final de capstone. É exatamente por esse passaporte e esse roteiro que você depois defenderá seu App diante de CTO/CEO.

14. Erros comuns ao preparar o passaporte e o demo

Erro nº 1: transformar o passaporte em um folheto de marketing.
Às vezes o passaporte passa a parecer um landing page: muitas palavras vazias sobre “IA inovadora”, pouca concretude sobre arquitetura, SLO, custo e incidentes. Um documento assim não ajuda ninguém: o técnico não entende como isso vive por dentro, e o negócio não vê que você controla os riscos. No passaporte devem haver fatos, esquemas, métricas e links.

Erro nº 2: descrever apenas o código, e não os fluxos de dados e responsabilidades.
Um viés comum entre desenvolvedores é listar todos os serviços, bibliotecas e frameworks, esquecendo o esquema de alto nível “usuário → ChatGPT → widget → MCP → agentes → ACP/BD”. Como resultado, uma pessoa nova não entende de quem são as responsabilidades e onde estão as fronteiras. Na seção de arquitetura, o mais importante são o data flow e as camadas, não os nomes de todos os pacotes npm.

Erro nº 3: não conectar o passaporte à observabilidade e à instrumentação de custo.
Acontece de o passaporte dizer com orgulho “temos SLO”, mas não aparecer como eles são medidos, onde estão os logs e quais campos são gravados nos eventos JSON. Ou dizer que “o custo de LLM está sob controle”, mas não haver nenhuma métrica de cost_per_task. Quanto menor a conexão com logs, métricas e dashboards reais, maior a chance de que SLO e custo vivam só no Google Docs, e não no sistema de monitoramento.

Erro nº 4: demo só sobre a UI bonita, sem arquitetura e tolerância a falhas.
É fácil cair no show: “vejam que cards de presentes legais”. A audiência técnica nesse momento pensa: “o que acontece se o Stripe cair?”, “como vocês registram as chamadas de tools?”, “isso escala?”. Se no demo você não mostrar pelo menos uma ou duas histórias sobre logs, SLO e incidentes, os técnicos sairão com a impressão de um brinquedo, não de um produto.

Erro nº 5: demo só para técnicos, sem a história do usuário e da economia.
O viés oposto: 10 minutos discutindo latência p95, handshake do MCP e JSON Schema dos tools, mas sem dizer qual dor do usuário é resolvida, quem paga e quanto custa um cenário. Para o negócio e produto, isso soa como “uma parada de engenharia muito legal sem business case”. Procure sempre vestir, no mínimo, dois chapéus: o do engenheiro e o do product manager.

Erro nº 6: passaporte e demo divergirem.
Às vezes, no passaporte está uma coisa e no demo — outra: no documento são prometidos certos SLO, mas nos dashboards aparecem outros; no passaporte há três incidentes com runbooks, mas na apresentação ao vivo, diante da primeira falha, todos entram em pânico. Tente usar o passaporte como roteiro do demo: referencie os mesmos SLO, os mesmos dashboards, os mesmos runbooks. Assim o público percebe um sistema coeso, não um conjunto de artefatos aleatórios.

Erro nº 7: tratar o passaporte como um trabalho de curso descartável.
A maior armadilha é escrever o PASSPORT.md para “entregar o módulo” e esquecê‑lo. Na vida real, é exatamente esse tipo de documento que impede a equipe de virar um zoológico de “conhecimento só na cabeça”. Procure tratar o passaporte como uma parte viva do código: que ele mude com decisões arquiteturais, operacionais ou de negócio relevantes. Daqui a alguns meses, você mesmo vai agradecer por isso.