Капстон‑інтеграція: техніко‑продуктове демо та «паспорт App»

1. Що таке «паспорт App» і навіщо він вам потрібен

Паспорт App — це компактний, але змістовний документ (зазвичай 1–2 сторінки Markdown або розділ у README). Він дає будь‑кому швидке уявлення про ваш ChatGPT App: як він влаштований, які має обмеження, як заробляє та як ви керуєте ним у продакшені.

Це не маркетингова брошура. Тут ідеться не про «найінноваційніші AI‑технології», а про цілком приземлені речі:

• де проходить межа між ChatGPT, вашим віджетом, MCP‑сервером, агентами та ACP/Stripe;
• які PII ви зберігаєте, як влаштовано OAuth/scopes і як відбувається ротація секретів;
• які у вас SLO щодо latency та availability, які є дашборди й алерти;
• скільки в середньому коштує один успішний сценарій і як ви за нього берете гроші;
• які типові інциденти вже описані та де зберігаються runbook-и;
• що ви плануєте робити з цим App у найближчі місяці.

Паспорт можна сприймати як агрегатор посилань і високорівневих описів. Він оновлюється рідше, ніж код, але частіше, ніж «офіційна презентація для інвесторів».

Для вас як розробника ChatGPT App паспорт — ще й чекліст зрілості. Якщо якийсь розділ порожній («а SLO ми якось не описали…»), це добрий тривожний сигнал. Отже, бракує не лише документації, а й самої практики.

2. Базова структура паспорта GiftGenius

Для GiftGenius доречно взяти таку структуру (ви можете трохи підлаштувати її під свій App, але загальна ідея збережеться).

Подамо це як невелику таблицю: хто що читає і навіщо.

Далі розглянемо кожен із цих блоків і паралельно складатимемо реальний PASSPORT.md для GiftGenius.

3. Архітектура: як показати весь стек на одній картинці

Архітектурний розділ — це серце паспорта. Тут не потрібно малювати UML‑діаграму на 200 прямокутників. Важливо показати шари та потоки: від користувача в ChatGPT до вашої БД і платіжної системи. Такий шлях типовий для ChatGPT App, що використовують Apps SDK і MCP.

Зручний формат — діаграма Mermaid прямо всередині PASSPORT.md. Наприклад, для 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)]

Під діаграмою ви коротко описуєте ключовий сценарій:

Користувач у чаті описує отримувача подарунка. Модель вирішує викликати tool suggest_gifts на MCP‑сервері. Агент може додатково читати каталоги як ресурси та виконувати кілька tools. Далі, під час вибору подарунка, створюється ACP‑сесія у Stripe, чекаут проходить через вебхуки, а результат зберігається в БД.

Добре, якщо ви одразу згадуєте технології: Next.js 16 + Apps SDK, MCP‑сервер на Node/Python, PostgreSQL, Redis для кешу, Stripe як платіжну систему.

До архітектурного розділу можна додати невеликий технічний фрагмент — щоб було видно, як архітектурні «цеглинки» проявляються в коді. Наприклад, фрагмент Next.js‑роуту, який передає requestId і userId у 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();      // трейс для логів
  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 });
}

Такий фрагмент допомагає повʼязати абстрактну стрілочку на діаграмі «Widget → MCP» із реальним кодом.

4. Security & Privacy: що саме потрібно зафіксувати

Безпека в паспорті — не про «ми використовуємо HTTPS і бекенд на TypeScript, тож усе нормально». Потрібні конкретні відповіді на запитання від безпеки, комплаєнсу та юридичного блоку.

Для GiftGenius варто коротко зафіксувати:

Яка модель автентифікації та авторизації:
для commerce‑сценаріїв використовується OAuth 2.1 з PKCE через MCP Auth Server; токен привʼязано до user_id і tenant_id, а всі tool‑виклики, повʼязані з чекаутом, вимагають scope commerce.checkout.

Які дані є PII і як ви з ними працюєте.
Наприклад: email і імʼя — PII, вподобання щодо подарунків — псевдоанонімні дані. У логи записуємо лише хешований email, адресу доставки не зберігаємо, а лише передаємо у Stripe і вебхуки.

Як влаштовані retention і видалення:
логи інструментів зберігаємо 30 днів, події commerce — 1 рік. На запит користувача можемо видалити його замовлення та повʼязані аналітичні події.

Як ви керуєте секретами:
коротко зазначте, де лежать OpenAI API key, Stripe secret, OAuth client secret (наприклад, у managed secret store), як часто ви їх ротуєте та як це тестується на staging.

У паспорті можна навести невеликий технічний фрагмент, щоб продемонструвати принцип «мінімально необхідних прав».

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

Далі в описі інструмента та MCP‑auth ви посилаєтеся на ці самі scopes. Це вже не просто слова про «least privilege», а конкретний контракт.

5. Observability і SLO: щоб бачити, як App живе

Наступний блок паспорта — про спостережуваність: як ви визначаєте, що App працює стабільно. Тут поєднуються структуровані логи, метрики, SLO та посилання на дашборди.

Для GiftGenius логічно описати:

Ключові SLO.
Наприклад: доступність MCP ≥ 99.5 %, p95 latency для suggest_gifts < 5 с, success‑rate для checkout ≥ 99 %.

Де дивитися ці SLO.
Назва й URL дашборда в Grafana/Datadog/… (у паспорті можна вказати просто «Dashboard: GiftGenius / SLO»).

Формат структурованих логів.
У попередньому модулі про спостережуваність ви вже продумали поля request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. У паспорті корисно навести невеликий приклад JSON, але можна зробити ще наочніше: оформити TypeScript‑тип, який використовується і в коді.

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

І helper‑функцію:

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

Тепер цей тип — місток між кодом і паспортом: у розділі Observability ви пишете, що всі tool‑виклики логуються у форматі ToolInvocationLog, і додаєте посилання на дашборд, який агрегує ці записи.

Можна додати коротку текстову схему:

Лог події → лог‑сховище → дашборди SLO → алерти → інцидент/runbook.

6. Economics & Product Metrics: гроші та поведінка користувачів

Тут ви зводите докупи все, що робили в попередньому блоці про економіку (М19): cost‑метрики, pricing і продуктову аналітику.

Для GiftGenius у паспорті варто закріпити:

Юніт‑економіку ключового сценарію (умовно — «економіку однієї завершеної задачі»).
Наприклад: «Середній cost_per_successful_task (підбір подарунка з успішною оплатою) = $0.13 (LLM + infra). Середня виручка per task = $0.80 (CPA від партнерів)».

Основну модель монетизації.
Коротко: «Безкоштовний базовий підбір без покупки, монетизація через CPA за перехід у магазин‑партнер + опційна premium‑підписка з розширеними фільтрами та історією подарунків».

Ключові продуктові метрики.
Наприклад: activation‑rate = частка користувачів, у яких був хоча б один workflow_completed; repeat‑rate = частка користувачів, які повернулися хоча б раз на місяць; конверсія workflow_completed → checkout_success.

Експерименти.
Список активних A/B‑тестів: «Модель A (дорога) vs модель B (дешева)», «Довгий майстер vs швидкий inline». Для кожного ви зберігаєте experiment_id, варіанти, цільові метрики (конверсія, cost_per_task, quality‑score).

У коді це теж можна показати, щоб паспорт не залишався теорією. Наприклад, через єдиний helper для аналітичних подій:

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

І виклик під час успішного завершення workflow:

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

У паспорті ви описуєте, які події є ключовими та які KPI на них завʼязані. Код — це доказ того, що ви справді щось вимірюєте, а не просто обіцяєте.

Але метрики й економіка мають сенс лише тоді, коли App стабільно працює в продакшені. Тож у наступному розділі розглянемо, як зафіксувати в паспорті операційну сторону життя GiftGenius: інциденти, on‑call і runbook-и.

7. Ops & Incidents: як ви житимете з App у продакшені

Цей розділ — про те, як ви реагуєте, коли щось іде не за планом.

Для GiftGenius має сенс у паспорті перелічити щонайменше два типові інциденти:

Проблеми з оплатою.
Наприклад: падіння success‑rate checkout нижче SLO, масові помилки у Stripe webhooks. У паспорті ви пишете, що для цього є runbook «Checkout Failures», де описано симптоми, де дивитися (дашборд помилок, логи webhook‑ендпойнта), швидкі кроки з помʼякшення наслідків (тимчасові заходи: вимкнути проблемний feature‑flag, перевести частину трафіку в sandbox або тимчасово пропонувати лише сертифікати) і подальші кроки (post‑mortem, додавання нових алертів).

Проблеми з MCP/LLM.
Наприклад: зростання p95 latency для suggest_gifts до 9 с або помилка «Error talking to app» для великого відсотка запитів. Тут — окремий runbook: перевірка статусу OpenAI, тунелю або Vercel, health‑check MCP, перемикання на деградований режим, у якому агент намагається відповідати без доступу до каталогу (загальні ідеї з моделі, без commerce).

У цьому ж розділі ви коротко описуєте операційний календар: як часто переглядаєте SLO, робите перегляд витрат (cost‑review), перевіряєте security‑логи та ротуєте секрети.

Тут же можна додати, хто on‑call (навіть якщо це одна людина — ви) і в який Slack‑канал або на яку пошту летять алерти.

8. Roadmap & Risks: чесний погляд уперед

Фінальний блок паспорта — про майбутнє. Тут не потрібно писати роман: достатньо 3–5 реальних кроків розвитку App і кількох відомих обмежень.

Для GiftGenius це може виглядати так:

• запуск LLM‑оцінок (LLM‑evals) для якості підборів, щоб повʼязати якість із конверсією;
• додавання ще однієї локалі та тестування локалізованих описів інструментів;
• експеримент із дешевшими моделями на частині трафіку;
• поліпшення стійкості до збоїв Stripe (надійніше обробляти вебхуки й відкладені підтвердження);
• підготовка до міграції на нову версію Apps SDK або MCP (з версіонуванням контрактів інструментів).

Обмеження: ліміти API, обмеження ChatGPT UI (наприклад, ліміт на кількість карток у видачі), слабкі місця поточної архітектури (однорегіонна БД, відсутність гарячого резерву MCP тощо).

План щодо експериментів: які гіпотези ви збираєтеся перевіряти щодо pricing/UX/моделей і за якими метриками ухвалюватимете рішення.

9. Де має жити паспорт і як його оновлювати

На практиці найзручніший формат — PASSPORT.md у корені репозиторію GiftGenius або в папці docs/, а також копія або посилання у вашій документаційній системі (Confluence, Notion тощо).

Він має бути достатньо легким, щоб його можна було прочитати за 10–15 хвилин, і достатньо щільним, щоб за ним можна було відповісти на запитання:

• «що це взагалі за App і як він влаштований?»
• «що буде, якщо впаде X?»
• «у скільки нам обходиться один користувач?»
• «які ризики нас зараз найбільше турбують?»

Оновлювати паспорт варто, коли змінюється:

• архітектурні межі (новий сервіс, нова платіжна система, міграція на інший стек);
• ключові SLO або політика безпеки (наприклад, інша retention);
• модель монетизації;
• значущі інциденти й висновки з post‑mortem‑ів.

Невеликі зміни коду не потребують негайного оновлення паспорта. Інакше він перетвориться на ще один документ, що швидко старіє.

Паспорт — це, по суті, концентрат усього, що ви знаєте про свій App. Наступний логічний крок — навчитися на його основі розповідати про продукт живим людям: і технічним фахівцям, і бізнесу.

10. Техніко‑продуктове демо: чому потрібні дві «версії розповіді»

Коли ви показуєте GiftGenius, ви майже завжди виступаєте перед двома типами аудиторії (іноді вони змішані в одній кімнаті):

• технічною (CTO, архітектори, security, лідери розробки);
• продуктово‑бізнесовою (CEO, інвестори, продуктові менеджери, маркетинг).

Технічній аудиторії важливо, що:

• архітектура зрозуміла, шари розділені, є точки розширення;
• надійність і спостережуваність продумані: логи, трейсинг, SLO, алерти;
• є історія про стійкість: що буде, якщо впаде OpenAI, MCP, Stripe;
• ви маєте план еволюції (міграція SDK/MCP/моделей).

Бізнесу важливіше інше:

• який у користувача біль (наприклад, «пошук подарунка займає 40 хвилин»);
• як GiftGenius цей біль розвʼязує в межах ChatGPT за кілька хвилин;
• яка у вас монетизація, юніт‑економіка та метрики зростання;
• чи знизить це вартість залучення клієнта, чи збільшить конверсію/виручку.

Тому мислити варто як про два «шари» однієї й тієї ж демо‑історії: ознаки зрілого продукту ви показуєте обом, але акценти — різні.

11. Сценарій технічного демо GiftGenius (5–7 хвилин)

Уявімо, що ви презентуєте GiftGenius технічній аудиторії.

Спершу — короткий контекст.
Буквально 30 секунд: «GiftGenius — ChatGPT App для підбору подарунків з ACP‑чекаутом. Ми працюємо всередині ChatGPT, використовуємо Apps SDK, MCP та агента для планування кроків».

Потім — архітектурний слайд або фрагмент із паспорта.
Ви відкриваєте діаграму, схожу на ту, що ми написали в Mermaid, і пояснюєте, де межа відповідальності ChatGPT (LLM‑частина), де ваш віджет, де MCP і де commerce‑шар зі Stripe. Тут корисно показати, що всі tools інкапсульовані в MCP, а віджет — тонкий UI‑шар.

Live‑демо з логами.
Далі ви вмикаєте split‑screen: ліворуч — ChatGPT з GiftGenius, праворуч — логи або MCP Inspector. Ставите природне запитання на кшталт «підібери подарунок для геймера до 50 $». У процесі виконання ви показуєте:

• tool‑виклик suggest_gifts із request_id;
• структурований лог tool_invocation, де видно tokens, cost_estimate і duration_ms;
• другий tool, який заводить ACP‑сесію та створює замовлення.

Чудово, якщо ви можете відразу показати дашборд: «а ось p95 latency цього сценарію за останню добу, а ось success‑rate checkout». Це момент, коли технічний фахівець розуміє: це не pet‑проєкт, а система зі спостережуваністю (observability).

Failure‑injection (опційно, але дуже ефектно).
Якщо ви достатньо впевнені в системі (або заздалегідь підготували сценарій), можна тимчасово вимкнути, скажімо, доступ до каталогу (БД) і повторити запит. Ви показуєте, що:

• MCP коректно записує помилку в логи і спрацьовує алерт;
• агент переходить у деградований режим і чесно каже користувачеві, що каталог недоступний, але може запропонувати загальні ідеї;
• checkout у такому режимі недоступний.

Наприкінці — коротко про експлуатацію та еволюцію.
Завершуєте слайдом із паспорта про SLO, інциденти й roadmap: які у вас цільові показники, як ви їх моніторите, які інциденти вже розібрані runbook-ами, що буде у v2 (масштабування, нові моделі, нові ринки).

Головний сигнал для аудиторії: у вас не просто красивий UI, а продумана платформа, готова до життя в продакшені.

12. Сценарій продуктового демо (бізнес‑ракурс)

Тепер той самий GiftGenius, але ви розповідаєте про нього як про продукт.

Починаєте з історії користувача.
Наприклад: «У нас є Катя. Їй потрібно за вечір вибрати подарунок колезі. Зазвичай вона витрачає на це 30–40 хвилин на сайтах магазинів».

Показуєте ChatGPT з GiftGenius.
Катя пише живу фразу, а не клікає по фільтрах у маркетплейсі: «підібери подарунок колезі, який любить настільні ігри, бюджет до 50 $». ChatGPT пояснює, що може використати GiftGenius, і відкриває віджет. GiftGenius уточнює кілька деталей і показує список варіантів.

Переходите до результату та цінності.
Показуєте картки подарунків, можливість зберегти або одразу перейти до покупки, чекаут через ACP/Stripe. Важливо сказати: «усе це займає 3–5 хвилин — і саме в тому місці, де користувач і так проводить час: у ChatGPT».

Далі — 1–2 хвилини про монетизацію та метрики.
Ви пояснюєте, що заробляєте на CPA або комісії з магазинів. Можливо, пропонуєте преміум‑режим для частих користувачів. Посилаєтеся на цифри з паспорта: скільки коштує один успішний сценарій, яка конверсія в покупку і який запас маржі закладено.

Далі — трохи про зростання.
Розповідаєте, як плануєте залучати користувачів: через Store‑лістинг у ChatGPT, контент, партнерські інтеграції. Але все привʼязуєте до продуктових метрик: «ми дивимося, як зміна лістингу впливає на число нових app_opened і activation‑rate; як статті та відео впливають на retention і частку користувачів із більш ніж одним workflow_completed».

Завершуєте ризиками та планом.
Чесно говорите про поточні обмеження (наприклад, що ви залежите від лімітів OpenAI/Stripe, що поки слабка підтримка локалей) і показуєте roadmap: які експерименти та поліпшення є в плані робіт.

Якщо все зробити акуратно, бізнес‑аудиторія побачить не лише «ще один AI‑віджет», а зрозумілий продукт з економікою та планом зростання.

13. Практика: збираємо свій паспорт і демо навколо GiftGenius

Як практичне завдання до цієї лекції ви можете прямо у своєму репозиторії GiftGenius створити файл PASSPORT.md і заповнити його щонайменше за пʼятьма блоками: архітектура, безпека, observability/SLO, економіка та продуктові метрики, інциденти/операції. Щойно ви допишете новий runbook або зміните SLO, повертайтеся до паспорта й відображайте цю зміну.

Паралельно варто зробити для себе конспект демо на 5–7 хвилин: перші 2–3 хвилини — користувацький сценарій і цінність, наступні 2–3 хвилини — архітектура та експлуатація (SLO, cost, інциденти). Такий конспект чудово тренує вміння говорити мовою і бізнесу, і техніки — не впадаючи ані в сухий код, ані в порожній маркетинг.

Ці артефакти — не «папірець для галочки», а основа фінального капстон‑демо. Саме за цим паспортом і сценарієм ви потім захищатимете свій App перед умовними CTO/CEO.

14. Типові помилки під час підготовки паспорта і демо

Помилка № 1: перетворити паспорт на маркетинговий буклет.
Іноді паспорт починає нагадувати лендинг: багато загальних слів про «інноваційний AI», мало конкретики про архітектуру, SLO, cost та інциденти. Такий документ нікому не допомагає: технічний фахівець не розуміє, як це працює всередині, а бізнес не бачить, що ви контролюєте ризики. У паспорті мають бути факти, схеми, метрики та посилання.

Помилка № 2: описувати лише код, а не потоки даних і зони відповідальності.
Популярний перекіс у розробників — перелічити всі сервіси, бібліотеки та фреймворки, забувши про високорівневу схему «користувач → ChatGPT → віджет → MCP → агенти → ACP/БД». У результаті нова людина не розуміє, де чиї обовʼязки і де проходять межі. В архітектурному розділі важливіші потоки даних і шари, а не назви всіх npm‑пакетів.

Помилка № 3: не повʼязати паспорт зі спостережуваністю (observability) і cost‑інструментацією.
Буває, що в паспорті гордо написано «у нас є SLO», але ніде не видно, як їх вимірюють, де логи і які саме поля пишуться в JSON‑події. Або написано, що «LLM‑cost під контролем», але немає жодної метрики cost_per_task. Чим менший звʼязок із реальними логами, метриками і дашбордами, тим більша ймовірність, що SLO і cost живуть лише в Google Docs, а не в системі моніторингу.

Помилка № 4: демо лише про гарний UI — без архітектури та відмовостійкості.
Легко звести все до шоу: «дивіться, які класні картки подарунків». Технічна аудиторія в цей момент думає: «а що буде, якщо Stripe впаде?», «як ви логуєте tool‑виклики?», «чи можна це масштабувати?». Якщо в демо не показати бодай одну‑дві історії про логи, SLO та інциденти, у технічних фахівців залишиться відчуття іграшки, а не продукту.

Помилка № 5: демо лише для технічної аудиторії — без історії користувача та економіки.
Зворотний перекіс: 10 хвилин обговорюємо p95 latency, MCP‑handshake і JSON Schema інструментів, але жодного разу не сказали, який біль користувача розвʼязуємо, хто платить і скільки коштує один сценарій. Для бізнесу та продуктового менеджера це виглядає як «крута інженерна штука без бізнес‑кейсу». Намагайтеся завжди тримати в голові щонайменше два «капелюхи»: інженера та продукт‑менеджера.

Помилка № 6: паспорт і демо розходяться.
Іноді в паспорті одне, а в демо — інше: у документі обіцяні одні SLO, а на дашбордах — інші; у паспорті три інциденти з runbook-ами, а в живій презентації при першому ж збої всі хапаються за голову. Намагайтеся використовувати паспорт як сценарій для демо: посилатися на ті ж SLO, ті ж дашборди, ті ж runbook-и. Тоді у слухачів виникає відчуття цілісної системи, а не набору випадкових артефактів.

Помилка № 7: ставитися до паспорта як до одноразової курсової.
Найбільша пастка — написати PASSPORT.md для здавання модуля й забути про нього. У реальному житті саме такі документи й перетворюють командні знання на хаотичний набір, який існує лише «в головах». Намагайтеся ставитися до паспорта як до живої частини коду: нехай він змінюється під час серйозних архітектурних, операційних або бізнес‑рішень. Тоді за кілька місяців ви самі скажете собі дякую.