Integrazione capstone: demo tecnico‑prodotto e «passaporto dell’App»

1. Che cos’è il «passaporto dell’App» e a cosa serve

Il passaporto dell’App è un documento compatto ma denso (di solito 1–2 pagine Markdown oppure una sezione nel README) che offre a chiunque una rapida comprensione della tua ChatGPT App: come è fatta, quali sono i suoi limiti, come monetizza e come la gestisci in produzione.

Non è una brochure di marketing. Non parla delle «tecnologie di AI più innovative», ma di aspetti molto concreti:

• dove passa il confine tra ChatGPT, il tuo widget, il server MCP, gli agenti e ACP/Stripe;
• quali PII conservi, come sono organizzati OAuth/scope e la rotazione dei segreti;
• quali SLO su latency e availability hai, quali dashboard e alert esistono;
• quanto costa in media uno scenario riuscito e come incassi per esso;
• quali incidenti tipici sono già documentati e dove si trovano i runbook;
• che cosa pianifichi di fare con questa App nei prossimi mesi.

Si può pensare al passaporto come a un aggregatore di link e descrizioni di alto livello, che cambia meno spesso del codice ma più spesso della «presentazione ufficiale per gli investitori».

Per te come sviluppatore di ChatGPT App il passaporto è anche una checklist di maturità. Se qualche sezione è vuota («e gli SLO non li abbiamo descritti…»), è un buon campanello d’allarme: significa che non manca solo la documentazione, ma anche la pratica stessa.

2. Struttura di base del passaporto di GiftGenius

Per GiftGenius ha senso adottare la seguente struttura (puoi adattarla leggermente alla tua App, ma l’idea generale resta).

Rappresentiamo in una piccola tabella chi legge cosa e perché:

Poi analizzeremo ciascuno di questi blocchi e, in parallelo, abbozzeremo un vero PASSPORT.md per GiftGenius.

3. Architettura: come mostrare l’intero stack in un’unica immagine

La sezione di architettura è il cuore del passaporto. Non serve disegnare un diagramma UML con 200 rettangoli. È importante mostrare i livelli e i flussi: dall’utente in ChatGPT fino al tuo DB e al sistema di pagamento. Per una ChatGPT App con Apps SDK e MCP, questo percorso è standard.

Un formato comodo è un diagramma Mermaid direttamente dentro PASSPORT.md. Per esempio, per 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)]

Nel testo sotto il diagramma descrivi lo scenario chiave:

L’utente in chat descrive il destinatario del regalo. Il modello decide di chiamare il tool suggest_gifts sul server MCP. L’agente può inoltre leggere i cataloghi come risorse ed eseguire più tool. Poi, quando si sceglie un regalo, viene creata una sessione ACP in Stripe, il checkout passa tramite i webhook e il risultato viene salvato nel DB.

Bene anche menzionare subito le tecnologie: Next.js 16 + Apps SDK, server MCP su Node/Python, PostgreSQL, Redis per la cache, Stripe come sistema di pagamento.

Si può aggiungere alla sezione architettura un piccolo frammento tecnico, per far vedere come i mattoni architetturali si manifestano nel codice. Per esempio, un pezzetto di route di Next.js che inoltra requestId e userId al 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();      // traccia per i log
  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 frammento del genere aiuta a collegare la freccia astratta nel diagramma «Widget → MCP» al codice reale.

4. Security & Privacy: che cosa va fissato esattamente

La sicurezza nel passaporto non è «usiamo HTTPS e un backend in TypeScript, quindi va tutto bene». Servono risposte concrete alle domande di sicurezza, compliance e legali.

Per GiftGenius vale la pena descrivere brevemente:

Quale modello di autenticazione e autorizzazione:
per gli scenari di commerce si usa OAuth 2.1 con PKCE tramite MCP Auth Server; il token è legato a user_id e tenant_id, tutte le chiamate di tool collegate al checkout richiedono lo scope commerce.checkout.

Quali dati sono PII e come li trattate.
Per esempio: email e nome — PII, le preferenze sui regali — dati pseudo‑anonimi; registriamo solo l’email hashata, non conserviamo l’indirizzo di consegna, ma lo inoltriamo soltanto a Stripe e ai webhook.

Come sono organizzati retention e cancellazione:
conserviamo i log degli strumenti per 30 giorni, gli eventi di commerce per 1 anno; su richiesta dell’utente possiamo eliminare i suoi ordini e gli eventi analitici collegati.

Come gestite i segreti:
descrivete brevemente dove risiedono OpenAI API key, Stripe secret, OAuth client secret (per esempio in un managed secret store), con quale frequenza vengono ruotati e come ciò viene testato in staging.

Nel passaporto puoi aggiungere un piccolo frammento tecnico per dimostrare il principio del «minimo privilegio necessario».

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

Poi, nella descrizione dello strumento e dell’autenticazione MCP, fai riferimento a questi stessi scope. Non sono più solo parole su «least privilege», ma un contratto concreto.

5. Observability e SLO: per vedere come vive l’App

Il blocco successivo del passaporto riguarda l’osservabilità: come capisci che l’App è viva e in salute. Qui si uniscono log strutturati, metriche, SLO e link ai dashboard.

Per GiftGenius ha senso descrivere:

Gli SLO chiave.
Per esempio: disponibilità MCP ≥ 99.5%, p95 latency per suggest_gifts < 5 secondi, success rate del checkout ≥ 99%.

Dove vedere questi SLO.
Nome e URL del dashboard in Grafana/Datadog/… (nel passaporto puoi indicare semplicemente «Dashboard: GiftGenius / SLO»).

Il formato dei log strutturati.
Nel modulo precedente sull’osservabilità hai già progettato i campi request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. Nel passaporto è utile fornire un piccolo esempio JSON, ma facciamo di meglio — definiamo un tipo TypeScript usato anche nel codice.

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

E una funzione helper:

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

Ora questo tipo diventa un ponte tra codice e passaporto: nella sezione Observability scrivi che tutte le invocazioni dei tool vengono loggate nel formato ToolInvocationLog e alleghi un link al dashboard che aggrega tali record.

Si può aggiungere uno schema testuale breve:

Log dell’evento → archivio log → dashboard SLO → alert → incidente/Runbook.

6. Economics & Product Metrics: denaro e comportamento degli utenti

Qui colleghi tutto ciò che hai fatto nel modulo precedente sull’economia (M19): metriche di costo, pricing e analitiche di prodotto.

Per GiftGenius nel passaporto conviene fissare:

L’unit economics dello scenario chiave (diciamo, «economia di un’attività completata»).
Per esempio: «cost_per_successful_task medio (selezione del regalo con pagamento riuscito) = $0.13 (LLM + infra). Ricavo medio per task = $0.80 (CPA dai partner).»

Il modello principale di monetizzazione.
In breve: «Selezione di base gratuita senza acquisto, monetizzazione tramite CPA per il passaggio al negozio partner + abbonamento premium opzionale con filtri avanzati e cronologia dei regali».

Le metriche di prodotto chiave.
Per esempio: activation rate = quota di utenti che hanno avuto almeno un workflow_completed; repeat rate = quota di utenti tornati almeno una volta al mese; conversione workflow_completed → checkout_success.

Esperimenti.
Elenco degli A/B attivi: «Modello A (costoso) vs Modello B (economico)», «Wizard lungo vs inline veloce». Per ciascuno conservi experiment_id, varianti, metriche target (conversione, cost_per_task, quality score).

Anche nel codice questo può emergere, affinché il passaporto non resti teoria, per esempio tramite un unico helper per gli eventi analitici:

// 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 la chiamata al completamento riuscito del workflow:

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

Nel passaporto descrivi quali eventi sono chiave e quali KPI vi sono collegati. Il codice è la prova che misurate davvero qualcosa, non solo promesse.

Ma metriche ed economia hanno senso solo quando l’App funziona stabilmente in produzione. Perciò nella sezione successiva vedremo come fissare nel passaporto il lato operativo della vita di GiftGenius: incidenti, on‑call e runbook.

7. Ops & Incidents: come vivrete con l’App in produzione

Questa sezione riguarda come reagite quando le cose non vanno secondo i piani.

Per GiftGenius ha senso elencare nel passaporto almeno due incidenti tipici:

Problemi di pagamento.
Per esempio: calo del success rate del checkout sotto gli SLO, errori diffusi dei webhook di Stripe. Nel passaporto scrivi che esiste un runbook «Checkout Failures», dove sono descritti i sintomi, dove guardare (dashboard degli errori, log dell’endpoint del webhook), passaggi rapidi di mitigazione (misure temporanee: disattivare il feature flag problematico, spostare parte del traffico in sandbox o offrire temporaneamente solo gift card) e follow‑up (post‑mortem, aggiunta di nuovi alert).

Problemi con MCP/LLM.
Per esempio: aumento della p95 latency per suggest_gifts fino a 9 secondi o errore «Error talking to app» per una grande percentuale di richieste. Qui un runbook dedicato: verifica dello stato di OpenAI, del tunnel/Vercel, health check del MCP, passaggio a una modalità degradata in cui l’agente prova a rispondere senza accesso al catalogo (idee generiche dal modello, senza commerce).

In questa stessa sezione descrivi brevemente il calendario operativo: quanto spesso rivedi gli SLO, fai il cost review, controlli i log di sicurezza e ruoti i segreti.

Puoi anche aggiungere chi è on‑call (anche se sei solo tu) e in quale canale Slack o a quale email arrivano gli alert.

8. Roadmap & Risks: uno sguardo onesto in avanti

Il blocco finale del passaporto riguarda il futuro. Non serve scrivere un romanzo. Bastano 3–5 passi reali di evoluzione dell’App e alcune limitazioni note.

Per GiftGenius potrebbe essere così:

• attivazione di LLM‑evals per la qualità delle proposte, per collegare qualità e conversione;
• aggiunta di un’altra locale e test delle descrizioni degli strumenti localizzate;
• esperimento con modelli più economici su parte del traffico;
• migliorare la resilienza ai guasti di Stripe (gestire in modo più affidabile i webhook e le conferme differite);
• preparazione alla migrazione alla nuova versione di Apps SDK o MCP (con versionamento dei contratti degli strumenti).

Limitazioni: cap degli API, limiti della UI di ChatGPT (per esempio, limite al numero di card nei risultati), punti deboli dell’architettura attuale (DB single‑region, assenza di hot standby per MCP, ecc.).

Piano degli esperimenti: quali ipotesi intendete verificare su pricing/UX/modelli e attraverso quali metriche prenderete le decisioni.

9. Dove far vivere il passaporto e come aggiornarlo

In pratica il formato più comodo è PASSPORT.md nella root del repository di GiftGenius o nella cartella docs/, nonché una copia/link nel vostro sistema di documentazione (Confluence, Notion, ecc.).

Deve essere abbastanza leggero da poter essere letto in 10–15 minuti e abbastanza denso da permettere di rispondere alle domande:

• «Che cos’è questa App, come è strutturata?»
• «Che cosa succede se cade X?»
• «Quanto ci costa un utente?»
• «Quali rischi ci preoccupano di più adesso?»

Aggiornare il passaporto conviene quando cambiano:

• i confini architetturali (nuovo servizio, nuovo sistema di pagamento, migrazione a un altro stack);
• gli SLO chiave o le policy di sicurezza (per esempio, retention diversa);
• il modello di monetizzazione;
• incidenti significativi e le conclusioni dei post‑mortem.

Piccole modifiche al codice non richiedono un aggiornamento immediato del passaporto, altrimenti diventerà un altro documento che invecchia.

Il passaporto è, in sostanza, il concentrato di tutto ciò che sai sulla tua App. Il passo logico successivo è imparare a raccontare il prodotto a persone in carne e ossa: tecniche e business.

10. Demo tecnico‑prodotto: perché servono due «versioni del racconto»

Quando mostri GiftGenius, quasi sempre ti rivolgi a due tipi di pubblico (a volte sono mescolati nella stessa stanza):

• tecnici (CTO, architetti, security, lead di sviluppo);
• pubblico prodotto/business (CEO, investitori, product manager, marketing).

Per una persona tecnica è importante che:

• l’architettura sia chiara, gli strati ben separati, ci siano punti di estensione;
• affidabilità e osservabilità siano pensate: log, tracing, SLO, alert;
• ci sia una storia di resilienza: che cosa succede se cadono OpenAI, MCP, Stripe;
• come pianificate l’evoluzione (migrazione di SDK/MCP/modelli).

Per il business conta altro:

• qual è il pain dell’utente (per esempio, «trovare un regalo richiede 40 minuti»);
• come GiftGenius risolve quel pain all’interno di ChatGPT in pochi minuti;
• qual è la vostra monetizzazione, l’unit economics e le metriche di crescita;
• se questo ridurrà il costo di acquisizione cliente, aumenterà conversione/ricavi.

Quindi conviene pensare a due «strati» della stessa storia di demo: i segni di un prodotto maturo li mostri a entrambi, ma con accenti diversi.

11. Scenario della demo tecnica di GiftGenius (5–7 minuti)

Immagina di presentare GiftGenius a un pubblico tecnico.

Prima un breve contesto.
Letteralmente 30 secondi: «GiftGenius è una ChatGPT App per la scelta dei regali con checkout ACP. Viviamo dentro ChatGPT, usiamo Apps SDK, MCP e un agente per pianificare i passi.»

Poi la slide di architettura/estratto dal passaporto.
Apri un diagramma simile a quello scritto in Mermaid e spieghi dove è il confine di responsabilità di ChatGPT (parte LLM), dove sta il tuo widget, dove MCP e dove il livello commerce con Stripe. Qui è utile mostrare che tutti i tool sono incapsulati in MCP e il widget è uno strato UI sottile.

Live demo con log.
Poi accendi uno split screen: a sinistra ChatGPT con GiftGenius, a destra i log o MCP Inspector. Fai una richiesta naturale tipo «scegli un regalo per un gamer fino a 50$». Durante l’esecuzione mostri:

• la chiamata del tool suggest_gifts con request_id;
• il log strutturato tool_invocation, dove si vedono tokens, cost_estimate e duration_ms;
• il tool secondario che apre la sessione ACP e crea l’ordine.

Fantastico se puoi subito aprire il dashboard: «ecco la p95 latency di questo scenario nelle ultime 24 ore, ecco il success rate del checkout». È il momento in cui il tecnico capisce che non è un pet project, ma un sistema con osservabilità.

Failure injection (opzionale, ma molto d’effetto).
Se sei abbastanza sicuro del sistema (o hai preparato lo scenario), puoi disattivare temporaneamente, ad esempio, l’accesso al catalogo (DB) e ripetere la richiesta. Mostri che:

• MCP registra correttamente l’errore e scatta un alert;
• l’agente passa in modalità degradata e dice onestamente all’utente che il catalogo non è disponibile, ma può fornire idee generiche;
• il checkout in tale modalità non è disponibile.

Alla fine — brevemente su esercizio ed evoluzione.
Chiudi con una slide dal passaporto con SLO, incidenti e roadmap: quali sono i tuoi obiettivi, come li monitori, quali incidenti sono già coperti dai runbook, cosa ci sarà nella v2 (scalabilità, nuovi modelli, nuovi mercati).

Il messaggio principale per il pubblico: non hai solo una UI carina, ma una piattaforma pensata per vivere in produzione.

12. Scenario della demo di prodotto (prospettiva business)

Lo stesso GiftGenius, ma raccontato come prodotto.

Inizia con la storia dell’utente.
Per esempio: «Abbiamo Katya, deve scegliere in serata un regalo per un collega. Di solito ci spende 30–40 minuti sui siti dei negozi».

Mostra ChatGPT con GiftGenius.
Katya scrive una frase naturale, invece di cliccare sui filtri in un marketplace: «scegli un regalo per un collega che ama i giochi da tavolo, budget fino a 50$». ChatGPT spiega che può usare GiftGenius e apre il widget. GiftGenius chiarisce un paio di dettagli e mostra un elenco di opzioni.

Passa al risultato e al valore.
Mostri le card dei regali, la possibilità di salvare o passare subito all’acquisto, checkout tramite ACP/Stripe. È importante dire: «tutto questo richiede 3–5 minuti, nel posto in cui l’utente già trascorre del tempo — in ChatGPT».

Poi 1–2 minuti su monetizzazione e metriche.
Spieghi che guadagni tramite CPA o commissioni dai negozi, magari offri una modalità premium per gli utenti frequenti. Ti riferisci alle cifre nel passaporto: quanto costa uno scenario riuscito, quale conversione verso l’acquisto e che margine è previsto.

Poi — un po’ sulla crescita.
Racconti come pianifichi di acquisire utenti: tramite lo Store listing in ChatGPT, contenuti, integrazioni con partner. Ma leghi tutto alle metriche di prodotto: «osserviamo come la modifica del listing influisce sul numero di nuovi app_opened e sull’activation rate; come articoli e video influenzano la retention e la quota di utenti con più di un workflow_completed».

Chiudi con rischi e piano.
Parli onestamente delle limitazioni attuali (ad esempio, dipendiamo dai limiti di OpenAI/Stripe, supporto delle localizzazioni ancora debole) e mostri la roadmap: quali esperimenti e miglioramenti sono nella pipeline.

Se fatto bene, il pubblico business vedrà non solo «l’ennesimo widget di AI», ma un prodotto comprensibile, con economia e piano di crescita.

13. Pratica: componiamo il tuo passaporto e la demo intorno a GiftGenius

Come esercizio per questa lezione puoi creare direttamente nel tuo repository GiftGenius il file PASSPORT.md e compilarlo almeno per cinque blocchi: architettura, sicurezza, observability/SLO, economia e metriche di prodotto, incidenti/operazioni. Non appena scrivi un nuovo runbook o modifichi un SLO, torna al passaporto e rifletti questo cambiamento.

In parallelo ha senso scrivere un canovaccio di demo da 5–7 minuti: i primi 2–3 minuti — scenario utente e valore, i successivi 2–3 — architettura ed esercizio (SLO, costi, incidenti). Un canovaccio del genere allena bene la capacità di parlare sia il linguaggio del business sia quello tecnico, senza scivolare né nel codice asciutto né nel marketing puro.

Questi artefatti non sono «carta per la forma», ma la base della demo capstone finale. Proprio su questo passaporto e su questo scenario poi difenderai la tua App davanti a CTO/CEO.

14. Errori tipici nella preparazione del passaporto e della demo

Errore n. 1: trasformare il passaporto in un opuscolo di marketing.
A volte il passaporto inizia ad assomigliare a una landing: molte parole generiche sulle «innovazioni dell’AI», poca concretezza su architettura, SLO, costi e incidenti. Un documento del genere non aiuta nessuno: il tecnico non capisce come viva internamente, e il business non vede che controllate i rischi. Nel passaporto devono esserci fatti, schemi, metriche e link.

Errore n. 2: descrivere solo il codice, non i flussi di dati e le responsabilità.
Un bias comune degli sviluppatori è elencare tutti i servizi, le librerie e i framework, dimenticando lo schema di alto livello «utente → ChatGPT → widget → MCP → agenti → ACP/DB». Di conseguenza, la persona nuova non capisce chi è responsabile di cosa e dove sono i confini. Nella sezione architettura sono più importanti il data flow e i livelli, non i nomi di tutti i pacchetti npm.

Errore n. 3: non collegare il passaporto a observability e strumentazione dei costi.
Capita che nel passaporto sia scritto con orgoglio «abbiamo gli SLO», ma non si vede da nessuna parte come siano misurati, dove sono i log e quali campi vengano scritti negli eventi JSON. Oppure che «il costo LLM è sotto controllo», ma non c’è una metrica cost_per_task. Quanto minore è il legame con log reali, metriche e dashboard, tanto maggiore la probabilità che SLO e costi vivano solo in Google Docs e non nel sistema di monitoraggio.

Errore n. 4: demo solo di UI carina, senza architettura e resilienza.
È facile scivolare nello show: «guardate che card di regali fantastiche». Il pubblico tecnico in quel momento pensa: «che succede se Stripe cade?», «come loggate le invocazioni dei tool?», «si può scalare?». Se nella demo non mostri almeno una‑due storie su log, SLO e incidenti, al tecnico resterà la sensazione di un giocattolo, non di un prodotto.

Errore n. 5: demo solo per tecnici, senza storia utente e economia.
Bias opposto: 10 minuti a discutere di p95 latency, handshake MCP e JSON Schema degli strumenti, senza mai dire qual è il pain dell’utente, chi paga e quanto costa uno scenario. Per business e product questo sembra «una gran cosa ingegneristica senza business case». Cerca sempre di tenere in testa almeno due cappelli: ingegnere e product manager.

Errore n. 6: passaporto e demo divergono.
A volte nel passaporto c’è una cosa e nella demo un’altra: nel documento sono promessi certi SLO, ma sui dashboard se ne vedono altri; nel passaporto tre incidenti con runbook, e nella presentazione live al primo guasto tutti vanno in panico. Prova a usare il passaporto come canovaccio della demo: riferisciti agli stessi SLO, agli stessi dashboard, agli stessi runbook. Allora l’ascoltatore percepisce un sistema coerente, non un insieme di artefatti casuali.

Errore n. 7: trattare il passaporto come una tesina usa e getta.
La trappola più grande è scrivere PASSPORT.md per consegnare il modulo e dimenticarsene. Nella vita reale proprio documenti simili trasformano il team in uno zoo di conoscenze «nella testa». Cerca di trattare il passaporto come una parte viva del codice: che cambi al mutare di decisioni architetturali, operative o di business importanti. Tra qualche mese ti ringrazierai da solo.