Intégration capstone : démo technico-produit et « passeport de l’app »

1. Qu’est-ce que le « passeport de l’app » et pourquoi vous en avez besoin

Le passeport de l’app est un document compact mais dense (généralement 1–2 pages Markdown ou une section dans le README) qui donne à toute personne une compréhension rapide de votre ChatGPT App : comment elle est conçue, quelles sont ses limites, comment elle gagne de l’argent et comment vous l’exploitez en production.

Ce n’est pas une brochure marketing. Il ne s’agit pas des « technologies d’IA les plus innovantes », mais de choses très terre à terre :

• où se trouve la frontière entre ChatGPT, votre widget, le serveur MCP, les agents et ACP/Stripe ;
• quelles PII vous stockez, comment sont conçus OAuth/scopes et la rotation des secrets ;
• quels SLO vous avez pour la latence et la disponibilité, quels tableaux de bord et alertes existent ;
• combien coûte en moyenne un scénario réussi et comment vous le monétisez ;
• quels incidents typiques sont déjà décrits et où se trouvent les runbooks ;
• ce que vous comptez faire avec cette app dans les prochains mois.

Vous pouvez voir le passeport comme un agrégateur de liens et de descriptions de haut niveau, qui change moins souvent que le code, mais plus souvent que « la présentation officielle pour les investisseurs ».

Pour vous, en tant que développeur de ChatGPT App, le passeport est aussi une checklist de maturité. Si une section est vide (« et nous n’avons pas décrit les SLO… »), c’est un bon signal d’alerte : cela signifie qu’il manque non seulement de la documentation, mais aussi la pratique elle‑même.

2. Structure de base du passeport GiftGenius

Pour GiftGenius, la structure suivante est logique (vous pouvez l’adapter légèrement à votre app, mais l’idée générale reste la même).

Présentons, sous forme de petit tableau, qui lit quoi et pourquoi :

Ensuite, nous détaillerons chacun de ces blocs et, en parallèle, nous commencerons à ébaucher un vrai PASSPORT.md pour GiftGenius.

3. Architecture : comment montrer toute la pile sur une seule image

La section architecture est le cœur du passeport. Inutile de dessiner un diagramme UML avec 200 rectangles. L’important est de montrer les couches et les flux : de l’utilisateur dans ChatGPT jusqu’à votre base de données et la solution de paiement. Pour une ChatGPT App avec Apps SDK et MCP, ce chemin est standard.

Un format pratique est un diagramme Mermaid directement dans PASSPORT.md. Par exemple, pour 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)]

Dans le texte sous le schéma, vous décrivez le scénario clé :

L’utilisateur décrit, dans le chat, le destinataire du cadeau. Le modèle décide d’appeler l’outil suggest_gifts sur le serveur MCP. L’agent peut en outre lire les catalogues comme ressources et exécuter plusieurs tools. Ensuite, lors du choix d’un cadeau, une session ACP est créée dans Stripe, le checkout se fait via des webhooks, et le résultat est enregistré dans la base de données.

Il est utile de mentionner tout de suite les technologies : Next.js 16 + Apps SDK, serveur MCP en Node/Python, PostgreSQL, Redis pour le cache, Stripe comme solution de paiement.

On peut ajouter à la section architecture un petit fragment technique pour montrer comment ces briques se traduisent dans le code. Par exemple, un extrait de route Next.js qui transmet requestId et userId au client 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 pour les 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 });
}

Un tel extrait aide à relier la flèche abstraite « Widget → MCP » du diagramme au code réel.

4. Security & Privacy : ce qu’il faut documenter précisément

La sécurité dans le passeport, ce n’est pas « nous utilisons HTTPS et un backend en TypeScript, donc tout va bien ». Il faut des réponses concrètes aux questions de sécurité, de conformité et juridiques.

Pour GiftGenius, décrivez brièvement :

Quel modèle d’authentification et d’autorisation :
pour les scénarios de commerce, OAuth 2.1 avec PKCE via MCP Auth Server est utilisé ; le jeton est lié à user_id et tenant_id, tous les appels d’outils liés au checkout exigent le scope commerce.checkout.

Quelles données sont des PII et comment vous les traitez.
Par exemple : l’email et le nom sont des PII, les préférences de cadeaux sont des données pseudonymisées ; nous journalisons uniquement l’email haché, l’adresse de livraison n’est pas stockée, elle est seulement transmise à Stripe et aux webhooks.

Comment sont gérées la rétention et la suppression :
nous conservons les logs des outils 30 jours, les événements de commerce 1 an, et sur demande de l’utilisateur nous pouvons supprimer ses commandes et les événements analytiques associés.

Comment vous gérez les secrets :
décrivez brièvement où se trouvent l’OpenAI API key, le Stripe secret, l’OAuth client secret (par exemple, dans un secret store managé), à quelle fréquence vous les faites tourner et comment c’est testé sur l’environnement de staging.

Dans le passeport, on peut inclure un court fragment orienté technique pour démontrer le principe du « moindre privilège ».

// 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;

Ensuite, dans la description de l’outil et du MCP‑auth, vous faites référence à ces mêmes scopes. Ce ne sont plus seulement des paroles sur le « least privilege », mais un contrat concret.

5. Observability et SLO : pour voir comment l’app vit

La section suivante du passeport concerne l’observabilité : comment vous savez que l’app est vivante et en bonne santé. Ici se rejoignent logs structurés, métriques, SLO et liens vers les tableaux de bord.

Pour GiftGenius, il est logique de décrire :

Les SLO clés.
Par exemple : disponibilité de MCP ≥ 99.5 %, p95 de latence pour suggest_gifts < 5 secondes, taux de succès du checkout ≥ 99 %.

Où consulter ces SLO.
Le nom et l’URL du tableau de bord dans Grafana/Datadog/… (dans le passeport, on peut indiquer simplement « Dashboard : GiftGenius / SLO »).

Le format des journaux structurés.
Dans le module précédent sur l’observabilité, vous avez déjà défini les champs request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. Dans le passeport, il est utile de donner un petit exemple JSON, mais faisons encore mieux — définissons un type TypeScript, utilisé aussi dans le code.

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

Et une fonction utilitaire :

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

Désormais, ce type devient un pont entre le code et le passeport : dans la section Observability, vous écrivez que tous les appels d’outils sont journalisés au format ToolInvocationLog, et vous joignez un lien vers le tableau de bord qui agrège ces enregistrements.

On peut ajouter un petit schéma textuel :

Journal d’événement → stockage des journaux → tableaux de bord SLO → alertes → incident/Runbook.

6. Economics & Product Metrics : argent et comportement des utilisateurs

Ici, vous reliez tout ce qui a été fait dans le bloc précédent sur l’économie (M19) : métriques de coûts, pricing et analytique produit.

Pour GiftGenius, il convient d’entériner dans le passeport :

L’unité d’économie du scénario clé (en gros, « l’économie d’une tâche aboutie »).
Par exemple : « Le cost_per_successful_task moyen (sélection du cadeau avec paiement réussi) = $0.13 (LLM + infra). Le revenu moyen par tâche = $0.80 (CPA des partenaires). »

Le modèle principal de monétisation.
En bref : « Sélection de base gratuite sans achat, monétisation via CPA pour la redirection vers une boutique partenaire + abonnement premium optionnel avec filtres avancés et historique des cadeaux ».

Les métriques produit clés.
Par exemple : activation‑rate = part d’utilisateurs ayant au moins un workflow_completed ; repeat‑rate = part d’utilisateurs revenus au moins une fois dans le mois ; conversion workflow_completed → checkout_success.

Les expériences.
La liste des A/B tests actifs : « Modèle A (cher) vs modèle B (moins cher) », « Assistant long vs inline rapide ». Pour chacun, vous conservez experiment_id, les variantes, les métriques cibles (conversion, cost_per_task, quality‑score).

On peut aussi le refléter dans le code pour éviter que le passeport reste théorique, par exemple via un helper unique pour les événements analytiques :

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

Et un appel lors de la réussite d’un workflow :

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

Dans le passeport, vous décrivez quels événements sont clés et quels KPI en dépendent. Le code constitue la preuve que vous mesurez réellement quelque chose, et pas seulement que vous le promettez.

Mais les métriques et l’économie n’ont de sens que lorsque l’app fonctionne de manière stable en production. Dans la section suivante, nous verrons donc comment consigner, dans le passeport, la vie opérationnelle de GiftGenius : incidents, astreinte et runbooks.

7. Ops & Incidents : comment vous vivrez avec l’app en production

Cette section porte sur la manière dont vous réagissez lorsque les choses ne se passent pas comme prévu.

Pour GiftGenius, il est pertinent de lister au moins deux incidents typiques :

Problèmes de paiement.
Par exemple : chute du taux de succès du checkout en‑dessous des SLO, erreurs massives des Stripe webhooks. Dans le passeport, vous écrivez qu’il existe un runbook « Checkout Failures », où sont décrits les symptômes, où regarder (tableau de bord des erreurs, logs de l’endpoint webhook), les étapes rapides de mitigation (mesures temporaires : désactiver le feature‑flag problématique, basculer une partie du trafic vers le sandbox ou proposer temporairement uniquement des cartes‑cadeaux) et le suivi (post‑mortem, ajout de nouvelles alertes).

Problèmes avec MCP/LLM.
Par exemple : montée du p95 de latence pour suggest_gifts jusqu’à 9 secondes ou erreur « Error talking to app » pour un grand pourcentage de requêtes. Ici, un runbook séparé : vérification du statut d’OpenAI, du tunnel/Vercel, health‑check du MCP, bascule vers un mode dégradé dans lequel l’agent essaie de répondre sans accès au catalogue (idées générales issues du modèle, sans commerce).

Dans cette même section, décrivez brièvement le calendrier opérationnel : à quelle fréquence vous révisez les SLO, faites un cost‑review, vérifiez les logs de sécurité et faites tourner les secrets.

Ajoutez aussi qui est d’astreinte (même si c’est une seule personne — vous), et dans quel canal Slack ou quelle adresse email arrivent les alertes.

8. Roadmap & Risks : regard lucide sur l’avenir

La section finale du passeport porte sur l’avenir. Inutile d’écrire un roman. Trois à cinq étapes réelles d’évolution de l’app et quelques limites connues suffisent.

Pour GiftGenius, cela peut ressembler à ceci :

• lancement des évaluations LLM (LLM‑evals) pour la qualité des sélections, afin de relier qualité et conversion ;
• ajout d’une autre locale et test des descriptions d’outils localisées ;
• expérience avec des modèles moins chers sur une partie du trafic ;
• amélioration de la résilience face aux pannes Stripe (traiter plus fiablement les webhooks et les confirmations différées) ;
• préparation de la migration vers une nouvelle version d’Apps SDK ou de MCP (avec versionnage des contrats d’outils).

Contraintes : quotas d’API, limites de l’UI ChatGPT (par exemple, limite sur le nombre de cartes dans les résultats), points faibles de l’architecture actuelle (base de données single‑region, absence de hot standby pour le MCP, etc.).

Plan d’expérimentation : quelles hypothèses vous comptez tester sur le pricing/UX/modèles et via quelles métriques vous prendrez des décisions.

9. Où vit le passeport et comment le mettre à jour

En pratique, le format le plus pratique est PASSPORT.md à la racine du dépôt GiftGenius ou dans le dossier docs/, ainsi qu’une copie/un lien dans votre système de documentation (Confluence, Notion, etc.).

Il doit être assez léger pour être lu en 10–15 minutes et assez dense pour permettre de répondre aux questions :

• « qu’est‑ce que c’est que cette app, comment est‑elle conçue ? »
• « que se passera‑t‑il si X tombe en panne ? »
• « combien nous coûte un utilisateur ? »
• « quels risques nous préoccupent le plus en ce moment ? »

Mettez à jour le passeport lors de changements :

• des frontières architecturales (nouveau service, nouvelle solution de paiement, migration vers un autre stack) ;
• des SLO clés ou des politiques de sécurité (par exemple, autre rétention) ;
• du modèle de monétisation ;
• d’incidents significatifs et des enseignements tirés des post‑mortems.

Les petits changements de code ne nécessitent pas de mise à jour immédiate du passeport, sinon il se transformera en un document rapidement obsolète.

Le passeport est, en substance, le concentré de tout ce que vous savez sur votre app. L’étape logique suivante est d’apprendre à s’en servir pour raconter le produit à des humains : des profils techniques et business.

10. Démo technico-produit : pourquoi il faut deux « versions de l’histoire »

Quand vous présentez GiftGenius, vous intervenez presque toujours devant deux types d’audience (parfois mélangés dans la même salle) :

• les profils techniques (CTO, architectes, sécurité, leads de développement) ;
• l’audience produit/business (CEO, investisseurs, product managers, marketing).

Pour un profil technique, l’important est que :

• l’architecture soit claire, les couches séparées, avec des points d’extension ;
• la fiabilité et l’observabilité soient réfléchies : logs, tracing, SLO, alertes ;
• il y ait une histoire de résilience : que se passe‑t‑il si OpenAI, MCP, Stripe tombent ;
• vous ayez un plan d’évolution (migration SDK/MCP/modèles).

Pour le business, l’important est autre :

• quelle est la douleur utilisateur (par exemple, « trouver un cadeau prend 40 minutes ») ;
• comment GiftGenius résout cette douleur dans ChatGPT en quelques minutes ;
• quel est votre modèle de monétisation, l’unité d’économie et les métriques de croissance ;
• si cela abaissera le coût d’acquisition client et augmentera la conversion/le revenu.

Il faut donc penser à deux « couches » d’une même histoire de démo : vous montrez des signes de maturité produit aux deux, mais avec des accents différents.

11. Scénario de démo technique GiftGenius (5–7 minutes)

Imaginons que vous présentez GiftGenius devant une audience technique.

Commencez par un bref contexte.
En 30 secondes : « GiftGenius est une ChatGPT App pour sélectionner des cadeaux avec un checkout ACP. Nous vivons dans ChatGPT, utilisons Apps SDK, MCP et un agent pour planifier les étapes. »

Puis la diapositive d’architecture/un extrait du passeport.
Vous ouvrez un diagramme proche de celui écrit en Mermaid et expliquez où se trouve la frontière de responsabilité de ChatGPT (partie LLM), où est votre widget, où est MCP et où est la couche commerce avec Stripe. Il est utile de montrer que tous les tools sont encapsulés dans le MCP, et que le widget est une fine couche d’UI.

Démo en direct avec logs.
Ensuite, vous passez en écran partagé : à gauche — ChatGPT avec GiftGenius, à droite — les logs ou MCP Inspector. Vous faites une requête naturelle du type « sélectionne un cadeau pour un gamer jusqu’à 50$ ». Pendant l’exécution, vous montrez :

• l’appel de tool suggest_gifts avec request_id ;
• le log structuré tool_invocation, où l’on voit tokens, cost_estimate et duration_ms ;
• un second tool qui initialise la session ACP et crée une commande.

C’est idéal si vous pouvez basculer aussitôt vers le tableau de bord : « voici le p95 de latence de ce scénario sur les dernières 24 h, voici le taux de succès du checkout ». C’est le moment où le profil technique comprend qu’il ne s’agit pas d’un pet‑project, mais d’un système observable.

Injection de pannes (optionnelle mais très efficace).
Si vous avez suffisamment confiance dans le système (ou un scénario préparé), vous pouvez désactiver temporairement, par exemple, l’accès au catalogue (base de données) et répéter la requête. Vous montrez que :

• le MCP journalise correctement l’erreur et une alerte se déclenche ;
• l’agent passe en mode dégradé et dit honnêtement à l’utilisateur que le catalogue est indisponible, mais peut fournir des idées génériques ;
• le checkout n’est pas disponible dans ce mode.

Pour finir — brièvement sur l’exploitation et l’évolution.
Terminez par une diapositive du passeport avec les SLO, les incidents et la roadmap : quels sont vos objectifs, comment vous les surveillez, quels incidents sont déjà couverts par des runbooks, ce qu’il y aura en v2 (scaling, nouveaux modèles, nouveaux marchés).

Le signal principal pour l’audience : vous n’avez pas seulement une belle UI, mais une plateforme pensée pour la production.

12. Scénario de démo produit (angle business)

Prenez maintenant le même GiftGenius, mais racontez‑le comme un produit.

Commencez par l’histoire utilisateur.
Par exemple : « Nous avons Katya, elle doit choisir un cadeau pour un collègue dans la soirée. D’habitude, elle y passe 30–40 minutes sur des sites marchands. »

Montrez ChatGPT avec GiftGenius.
Katya écrit une phrase naturelle, au lieu de cliquer sur des filtres d’un marketplace : « sélectionne un cadeau pour un collègue qui aime les jeux de société, budget jusqu’à 50$ ». ChatGPT explique qu’il peut utiliser GiftGenius et ouvre le widget. GiftGenius précise quelques détails et affiche une liste d’options.

Passez au résultat et à la valeur.
Vous montrez les cartes des cadeaux, la possibilité d’enregistrer ou d’acheter tout de suite, le checkout via ACP/Stripe. Il est important de dire : « tout cela prend 3–5 minutes, là où l’utilisateur passe déjà du temps — dans ChatGPT ».

Ensuite, 1–2 minutes sur la monétisation et les métriques.
Vous expliquez que vous gagnez via le CPA ou une commission des boutiques, et proposez éventuellement un mode premium pour les utilisateurs fréquents. Vous vous référez aux chiffres du passeport : combien coûte un scénario réussi, quel est le taux de conversion vers l’achat et quelle marge est prévue.

Puis un mot sur la croissance.
Expliquez comment vous comptez acquérir des utilisateurs : via la fiche Store dans ChatGPT, du contenu, des intégrations partenaires. Mais rattachez tout aux métriques produit : « nous regardons comment la modification de la fiche impacte le nombre de nouveaux app_opened et l’activation ; comment les articles et vidéos affectent la rétention et la part d’utilisateurs avec plus d’un workflow_completed ».

Concluez par les risques et le plan.
Soyez honnête sur les limites actuelles (par exemple, votre dépendance aux limites OpenAI/Stripe, un support des locales encore faible) et montrez la roadmap : quelles expériences et améliorations sont dans le pipeline.

Si tout est fait proprement, l’audience business verra non seulement « un widget IA de plus », mais un produit clair avec une économie et un plan de croissance.

13. Pratique : construire votre passeport et votre démo autour de GiftGenius

En guise de pratique pour ce cours, vous pouvez créer directement dans votre dépôt GiftGenius un fichier PASSPORT.md et le remplir avec au moins cinq blocs : architecture, sécurité, observability/SLO, économie et métriques produit, incidents/opérations. Dès que vous rédigez un nouveau runbook ou modifiez un SLO, revenez au passeport et reflétez ce changement.

En parallèle, il est utile de vous écrire un script de démo de 5–7 minutes : les 2–3 premières — le scénario utilisateur et la valeur, les 2–3 suivantes — l’architecture et l’exploitation (SLO, coûts, incidents). Un tel script entraîne parfaitement la capacité à parler à la fois le langage du business et de la technique, sans tomber ni dans le code sec ni dans le marketing pur.

Ces artefacts ne sont pas « un papier pour la forme », mais la base de la démo capstone finale. C’est précisément avec ce passeport et ce scénario que vous défendrez ensuite votre app devant des CTO/CEO.

14. Erreurs typiques lors de la préparation du passeport et de la démo

Erreur n° 1 : transformer le passeport en brochure marketing.
Parfois, le passeport commence à ressembler à une landing page : beaucoup de généralités sur « l’IA innovante », peu de concret sur l’architecture, les SLO, les coûts et les incidents. Un tel document n’aide personne : un profil technique ne voit pas comment ça vit à l’intérieur, et le business ne voit pas que vous contrôlez les risques. Le passeport doit contenir des faits, des schémas, des métriques et des liens.

Erreur n° 2 : ne décrire que le code, pas les flux de données ni les responsabilités.
Un biais courant chez les développeurs est d’énumérer tous les services, bibliothèques et frameworks, en oubliant le schéma de haut niveau « utilisateur → ChatGPT → widget → MCP → agents → ACP/base de données ». Résultat : une nouvelle personne ne comprend pas qui fait quoi ni où passent les frontières. Dans la section architecture, le data flow et les couches sont plus importants que les noms de tous les paquets npm.

Erreur n° 3 : ne pas relier le passeport à l’observabilité et à l’instrumentation des coûts.
Il arrive que le passeport proclame fièrement « nous avons des SLO », mais on ne voit nulle part comment ils sont mesurés, où sont les logs ni quels champs sont écrits dans les événements JSON. Ou qu’il est écrit « les coûts LLM sont sous contrôle », mais qu’il n’y a aucune métrique cost_per_task. Moins il y a de lien avec de vrais logs, métriques et tableaux de bord, plus il est probable que SLO et coûts ne vivent que dans Google Docs, et non dans le système de monitoring.

Erreur n° 4 : une démo seulement sur une belle UI, sans architecture ni tolérance aux pannes.
Il est facile de tomber dans le show : « regardez ces super cartes cadeaux ». L’audience technique pense alors : « que se passe‑t‑il si Stripe tombe ? », « comment journalisez‑vous les appels d’outils ? », « est‑ce que ça passe à l’échelle ? ». Si la démo ne montre pas au moins une ou deux histoires de logs, SLO et incidents, les profils techniques garderont l’impression d’un jouet, pas d’un produit.

Erreur n° 5 : une démo seulement pour les techniciens, sans histoire utilisateur ni économie.
Biais inverse : 10 minutes à discuter du p95 de latence, du handshake MCP et des JSON Schema des outils, sans jamais dire quelle douleur utilisateur est résolue, qui paie et combien coûte un scénario. Pour le business et le produit, cela ressemble à « une super prouesse d’ingénierie sans business case ». Essayez de garder au moins deux casquettes en tête : ingénieur et product manager.

Erreur n° 6 : le passeport et la démo divergent.
Parfois, le passeport dit une chose et la démo une autre : le document promet certains SLO, mais les tableaux de bord en montrent d’autres ; le passeport liste trois incidents avec runbooks, mais lors de la présentation en direct, au premier incident, tout le monde est perdu. Essayez d’utiliser le passeport comme scénario pour la démo : référez‑vous aux mêmes SLO, aux mêmes tableaux de bord, aux mêmes runbooks. L’audience aura alors l’impression d’un système cohérent, pas d’un assemblage d’artefacts.

Erreur n° 7 : considérer le passeport comme un devoir unique.
Le plus grand piège est d’écrire PASSPORT.md pour valider le module et de l’oublier. Dans la vraie vie, ce sont précisément ces documents qui évitent que l’équipe devienne un zoo de connaissances tacites. Essayez de traiter le passeport comme une partie vivante du code : qu’il évolue lors de décisions d’architecture, d’exploitation ou business majeures. Dans quelques mois, vous vous en remercierez.