Capstone integration: technical‑product demo and “App passport”

1. What an “App passport” is and why you need it

An App passport is a compact yet dense document (typically 1–2 pages of Markdown or a section in the README) that gives anyone a quick understanding of your ChatGPT App: how it’s built, what constraints it has, how it makes money, and how you operate it in production.

This is not a marketing brochure. It’s not about “the most innovative AI technologies,” but about very down‑to‑earth things:

• where the boundary runs between ChatGPT, your widget, the MCP server, agents, and ACP/Stripe;
• what PII you store, how OAuth/scopes and secret rotation are set up;
• what SLOs you have for latency and availability, and what dashboards and alerts exist;
• how much a successful flow costs on average and how you charge for it;
• which typical incidents are already documented and where the runbooks live;
• what you plan to do with this App in the coming months.

You can think of the passport as an aggregator of links and high‑level descriptions that changes less often than code but more often than the “official investor deck.”

For you as a ChatGPT App developer, the passport is also a maturity checklist. If some section is empty (“we somehow didn’t define the SLOs…”), that’s a good red flag: it means not only the documentation is missing, but the practice itself.

2. Baseline structure of the GiftGenius passport

For GiftGenius it’s logical to use the following structure (you can slightly adapt it to your App, but the overall idea remains).

Let’s present a small table of who reads what and why:

Next, we’ll break down each of these blocks and in parallel draft a real PASSPORT.md for GiftGenius.

3. Architecture: how to show the whole stack on one diagram

The architecture section is the heart of the passport. You don’t need a UML diagram with 200 rectangles. It’s important to show the layers and flows: from a user in ChatGPT to your DB and the payment system. For a ChatGPT App with the Apps SDK and MCP this path is standard.

A convenient format is a Mermaid diagram right inside PASSPORT.md. For example, for 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)]

In the text under the diagram, describe the key scenario:

The user in chat describes the gift recipient. The model decides to call the tool suggest_gifts on the MCP server. The agent can additionally read catalogs as resources and execute several tools. Then, when a gift is chosen, an ACP session in Stripe is created, checkout goes through webhooks, and the result is saved to the DB.

It’s good if you also mention the technologies: Next.js 16 + Apps SDK, an MCP server on Node/Python, PostgreSQL, Redis for cache, Stripe as the payment processor.

You can add a small technical fragment to show how the architectural building blocks surface in code. For example, a snippet of a Next.js route that passes requestId and userId into the MCP client:

// 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 for 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 });
}

Such a snippet helps tie the abstract “Widget → MCP” arrow on the diagram to real code.

4. Security & Privacy: what exactly to capture

Security in the passport is not about “we use HTTPS and a TypeScript backend, so everything is fine.” You need concrete answers to security, compliance, and legal questions.

For GiftGenius briefly describe:

What authentication and authorization model you use:
for commerce scenarios, OAuth 2.1 with PKCE via an MCP Auth Server; the token is bound to user_id and tenant_id, and all tool calls related to checkout require the commerce.checkout scope.

Which data are PII and how you handle them.
For example: email and name are PII, gift preferences are pseudo‑anonymous data; we log only a hashed email, do not store the shipping address—only pass it to Stripe and webhooks.

How retention and deletion are set up:
tool logs are kept for 30 days, commerce events for 1 year; upon user request we can delete their orders and associated analytics events.

How you manage secrets:
briefly describe where the OpenAI API key, Stripe secret, and OAuth client secret live (e.g., in a managed secret store), how often you rotate them, and how this is tested in staging.

In the passport you can add a small engineer‑oriented fragment to demonstrate the “least privilege” principle.

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

Later, in the tool description and MCP auth, you reference these same scopes. This is no longer just words about least privilege, but a concrete contract.

5. Observability and SLO: to see how the App is doing

The next block of the passport is about observability: how you know the App is alive and healthy. Here you bring together structured logs, metrics, SLOs, and links to dashboards.

For GiftGenius it makes sense to outline:

Key SLOs.
For example: MCP availability ≥ 99.5%, p95 latency for suggest_gifts < 5 seconds, checkout success rate ≥ 99%.

Where to view these SLOs.
The name and URL of the dashboard in Grafana/Datadog/… (in the passport you can simply state “Dashboard: GiftGenius / SLO”).

Format of structured logs.
In the previous observability module you already thought through fields like request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. In the passport it’s useful to provide a small JSON example, but we can go further—define a TypeScript type that’s used in code.

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

And a helper function:

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

Now this type becomes a bridge between code and the passport: in the Observability section you state that all tool calls are logged in the ToolInvocationLog format and include a link to the dashboard that aggregates these records.

You can also add a short textual pipeline:

Event log → log store → SLO dashboards → alerts → incident/runbook.

6. Economics & Product Metrics: money and user behavior

Here you connect everything you did in the previous economics block (M19): cost metrics, pricing, and product analytics.

For GiftGenius the passport should codify:

Unit economics of the key flow (roughly, “the economics of one completed task”).
For example: “Average cost_per_successful_task (gift selection with successful payment) = $0.13 (LLM + infra). Average revenue per task = $0.80 (CPA from partners).”

The main monetization model.
Briefly: “Free basic suggestions without purchase; monetization via CPA for redirecting to partner stores + an optional premium subscription with advanced filters and gift history.”

Key product metrics.
For example: activation rate = the share of users who had at least one workflow_completed; repeat rate = the share of users who returned at least once within a month; conversion workflow_completed → checkout_success.

Experiments.
A list of active A/Bs: “Model A (expensive) vs Model B (cheap),” “Long wizard vs fast inline.” For each you keep an experiment_id, variants, and target metrics (conversion, cost_per_task, quality score).

You can also reflect this in code so the passport isn’t just theory, for example via a single helper for analytics events:

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

And a call on successful workflow completion:

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

In the passport, describe which events are key and which KPIs depend on them. Code is the proof that you actually measure something, not just promise to.

But metrics and economics only make sense when the App runs stably in production. So in the next section we’ll see how to capture the operational side of GiftGenius in the passport: incidents, on‑call, and runbooks.

7. Ops & Incidents: how you will live with the App in production

This section is about how you react when things don’t go as planned.

For GiftGenius it makes sense to list at least two typical incidents:

Payment issues.
For example: checkout success rate falling below the SLO, mass errors in Stripe webhooks. In the passport, note that there’s a “Checkout Failures” runbook describing symptoms, where to look (error dashboard, logs of the webhook endpoint), quick mitigation steps (temporary measures: disable a problematic feature flag, route some traffic to sandbox, or temporarily offer gift cards only), and follow‑up (post‑mortem, adding new alerts).

MCP/LLM issues.
For example: p95 latency for suggest_gifts rising to 9 seconds or “Error talking to app” for a large share of requests. Here you have a separate runbook: check OpenAI status, the tunnel/Vercel, MCP health check, switch to a degraded mode in which the agent tries to respond without catalog access (general ideas from the model, no commerce).

In this section you also briefly describe the operational calendar: how often you review SLOs, conduct cost reviews, check security logs, and rotate secrets.

Also add who is on‑call (even if it’s just you) and which Slack channel or email receives alerts.

8. Roadmap & Risks: a candid look ahead

The final block of the passport is about the future. You don’t need to write a novel. Three to five realistic steps for App development and a few known constraints are enough.

For GiftGenius, it might look like this:

• launch LLM‑based evaluations (LLM evals) of suggestion quality to tie quality to conversion;
• add another locale and test localized tool descriptions;
• experiment with cheaper models on part of the traffic;
• improve resilience to Stripe outages (more robust webhook handling and delayed confirmations);
• prepare for migration to a new version of the Apps SDK or MCP (with versioned tool contracts).

Constraints: API caps, ChatGPT UI limits (e.g., the number of cards in results), weak points of the current architecture (single‑region DB, no hot standby for MCP, etc.).

Plan for experiments: which hypotheses you will test around pricing/UX/models and which metrics you’ll use to make decisions.

9. Where the passport should live and how to update it

In practice the most convenient format is PASSPORT.md at the root of the GiftGenius repository or in the docs/ folder, as well as a copy/link in your documentation system (Confluence, Notion, etc.).

It should be light enough to read in 10–15 minutes, and dense enough to answer questions like:

• “what is this App, and how is it built?”
• “what happens if X fails?”
• “how much does one user cost us?”
• “which risks worry us the most right now?”

Update the passport when the following change:

• architectural boundaries (a new service, a new payment system, a migration to a different stack);
• key SLOs or security policy (for example, different retention);
• the monetization model;
• material incidents and conclusions from post‑mortems.

Minor code changes do not require immediate edits to the passport, otherwise it will turn into yet another stale document.

The passport is, essentially, a concentrate of everything you know about your App. The next logical step is to learn to present the product to real people—engineers and business—based on it.

10. Technical‑product demo: why you need two “versions of the story”

When you show GiftGenius, you’re almost always presenting to two types of audiences (sometimes mixed in the same room):

• technical folks (CTO, architects, security, engineering leads);
• product/business audience (CEO, investors, product managers, marketing).

For a technical person, it’s important that:

• the architecture is clear, layers are separated, and there are extension points;
• reliability and observability are thought through: logs, tracing, SLOs, alerts;
• there’s a resilience story: what happens if OpenAI, MCP, or Stripe goes down;
• you have a plan for evolution (migration of SDK/MCP/models).

Business cares more about:

• what user pain exists (for example, “searching for a gift takes 40 minutes”);
• how GiftGenius solves that pain within ChatGPT in a few minutes;
• what your monetization, unit economics, and growth metrics are;
• whether this will lower customer acquisition cost and increase conversion/revenue.

Therefore, think of two “layers” of the same demo story: you show signs of a mature product to both, but the emphasis differs.

11. Technical demo script for GiftGenius (5–7 minutes)

Imagine you’re presenting GiftGenius to a technical audience.

Start with brief context.
Literally 30 seconds: “GiftGenius is a ChatGPT App for gift picking with ACP checkout. We live inside ChatGPT, use the Apps SDK, MCP, and an agent to plan steps.”

Then an architecture slide/fragment from the passport.
Open a diagram like the one we wrote in Mermaid and explain where ChatGPT’s responsibility ends (the LLM part), where your widget is, where MCP is, and where the commerce layer with Stripe lives. It’s useful to show that all tools are encapsulated in MCP and the widget is a thin UI layer.

Live demo with logs.
Turn on a split screen: on the left—ChatGPT with GiftGenius, on the right—logs or an MCP Inspector. Make a natural request like “suggest a gift for a gamer under $50.” As it runs, show:

• a suggest_gifts tool call with a request_id;
• a structured tool_invocation log showing tokens, cost_estimate, and duration_ms;
• a secondary tool that creates an ACP session and opens an order.

It’s great if you can immediately point to a dashboard: “here’s the p95 latency of this scenario over the last 24 hours, here’s the checkout success rate.” That’s when an engineer realizes this isn’t a pet project but a system with observability.

Failure injection (optional but very impactful).
If you’re confident enough in the system (or have prepared a scenario), you can temporarily disable, say, catalog (DB) access and repeat the request. Show that:

• MCP logs the error correctly and an alert fires;
• the agent switches to a degraded mode and honestly tells the user the catalog is unavailable but can provide generic ideas;
• checkout is unavailable in this mode.

End with a quick note on operations and evolution.
Close with a slide from the passport with SLOs, incidents, and the roadmap: your targets, how you monitor them, which incidents already have runbooks, and what’s in v2 (scaling, new models, new markets).

The main signal to the audience: you don’t just have a pretty UI—you have a thoughtful platform ready for life in production.

12. Product demo script (business angle)

Now the same GiftGenius, but told as a product.

Start with a user story.
For example: “We have Katya; she needs to pick a gift for a colleague this evening. She usually spends 30–40 minutes browsing online stores.”

Show ChatGPT with GiftGenius.
Katya writes a natural phrase instead of clicking filters in a marketplace: “suggest a gift for a colleague who loves board games, budget up to $50.” ChatGPT explains it can use GiftGenius and opens a widget. GiftGenius clarifies a couple of details and shows a list of options.

Move to the outcome and value.
Show gift cards, the ability to save or proceed to purchase, checkout via ACP/Stripe. It’s important to say: “this takes 3–5 minutes and happens where the user already spends time—in ChatGPT.”

Then 1–2 minutes on monetization and metrics.
Explain that you earn via CPA or commissions from stores, and you may offer a premium mode for frequent users. Reference figures from the passport: how much a successful flow costs, what the purchase conversion is, and what margin buffer you have.

Next—a bit about growth.
Tell how you plan to acquire users: through the Store listing in ChatGPT, content, partner integrations. Tie it to product metrics: “we track how listing changes affect new app_opened and activation rate; how articles and videos affect retention and the share of users with more than one workflow_completed.”

Finish with risks and the plan.
Be honest about current constraints (for example, dependence on OpenAI/Stripe limits, weak locale support for now), and show the roadmap: which experiments and improvements are in the pipeline.

If done carefully, the business audience will see not just “another AI widget,” but a clear product with economics and a growth plan.

13. Practice: assemble your own passport and demo around GiftGenius

As practice for this lecture, you can create a PASSPORT.md file right in your GiftGenius repository and fill at least five blocks: architecture, security, observability/SLO, economics and product metrics, incidents/operations. As soon as you add a new runbook or change an SLO, come back to the passport and reflect that change.

In parallel, it makes sense to write yourself a 5–7‑minute demo outline: the first 2–3 minutes—user scenario and value; the next 2–3—architecture and operations (SLOs, cost, incidents). Such an outline is great practice for speaking both the business and engineering languages without slipping into dry code or empty marketing.

These artifacts are not “paperwork for a checkbox,” but the foundation of the final capstone demo. You will defend your App before a hypothetical CTO/CEO using exactly this passport and script.

14. Common mistakes when preparing the passport and the demo

Mistake #1: turning the passport into a marketing brochure.
Sometimes the passport starts to look like a landing page: lots of generic words about “innovative AI,” little concreteness about architecture, SLOs, cost, and incidents. Such a document helps no one: engineers don’t understand how it lives inside, and business doesn’t see that you control risks. The passport should contain facts, diagrams, metrics, and links.

Mistake #2: describing only code, not data flows and responsibilities.
A popular developer bias is to list all services, libraries, and frameworks, forgetting the high‑level “user → ChatGPT → widget → MCP → agents → ACP/DB” scheme. As a result, newcomers don’t understand who owns what and where the boundaries lie. In the architecture section, data flow and layers matter more than listing every npm package.

Mistake #3: not tying the passport to observability and cost instrumentation.
It happens that the passport proudly states “we have SLOs,” but nowhere is it visible how they’re measured, where the logs are, and which exact fields go into JSON events. Or it says “LLM costs are under control,” but there’s not a single cost_per_task metric. The less connection to real logs, metrics, and dashboards, the more likely SLOs and costs live only in Google Docs and not in the monitoring system.

Mistake #4: a demo only about a pretty UI, without architecture and resilience.
It’s easy to slip into a show: “look at these beautiful gift cards.” The technical audience is thinking: “what if Stripe goes down?”, “how do you log tool calls?”, “can this scale?” If the demo doesn’t show at least one or two stories about logs, SLOs, and incidents, engineers will feel it’s a toy, not a product.

Mistake #5: a demo only for engineers, without a user story and economics.
The opposite bias: 10 minutes discussing p95 latency, the MCP handshake, and tool JSON Schemas, but never mentioning which user pain you solve, who pays, and how much one flow costs. For business and product this looks like “a cool engineering thing without a business case.” Always try to keep at least two hats in mind: engineer and product manager.

Mistake #6: the passport and the demo diverge.
Sometimes the passport says one thing and the demo shows another: the document promises one set of SLOs, but the dashboards show another; the passport claims three incidents with runbooks, but in the live presentation everyone panics at the first failure. Try to use the passport as the script for the demo: reference the same SLOs, the same dashboards, the same runbooks. Then the listener feels a cohesive system, not a pile of accidental artifacts.

Mistake #7: treating the passport as a one‑off coursework.
The biggest trap is to write PASSPORT.md just to pass a module and forget about it. In real life, such documents keep teams from turning into a zoo of tribal knowledge. Treat the passport as a living part of the codebase: let it change with serious architectural, operational, or business decisions. In a couple of months, you’ll thank yourself.