Abitly Marketing (re-engagement + продажі)

Метадані

Поле	Значення
Продукт	Abitly.org
Тип	Backend / worker (orchestration)
Статус	🚧 в розробці (план)
Власник	@Vladbandurin

Призначення

Re-engagement сплячих абітурієнтів і продажі (Premium / Subscription / Tokens) через персоналізовані розсилки в email і Telegram. Персоналізація будується AI на інтент-сигналах: які Offer (ЗВО + спеціальність) контакт моніторить, його NMT-профіль і дедлайни зі Strapi.

Архітектурні рішення (ledger)

#	Рішення	Джерело
D1	North-star — campaign-attributed revenue; аудиторія сегментована за lifecycle stage; минулий цикл → крос-сейл на Studsearch	—
D2	Контакт = `BaseUser`; identity-resolution (link Telegram→`BaseUser` on auth)	глосарій
D3	Re-permission-first: перша кампанія = win-back + преференс-центр на окремому прогрітому домені, після list hygiene	ADR-1
D4	Власна оркестрація + куплена доставка (ESP за swappable-інтерфейсом)	ADR-1
D5	Дані — окрема схема `marketing` на shared RDS (C2) + guardrails	ADR-2
D6	Персоналізація L2 (AI per-segment copy) + L3 для high-value тригерів	—
D7	Grounded generation: AI пише обгортку, факти — детермінований merge + валідатор	ADR-3
D8	Approval queue — людина схвалює копію перед відправкою	—
D9	v1 = batch Campaigns на BullMQ; Journeys = v2	—
D10	Safety rails: suppression + frequency cap + quiet hours з 1 дня	—
D11	Last-touch attribution: `campaign_id` → lake-house → join з Monobank-покупками	payments

Бізнес-дефолти: hero-offer = Premium; tone = peer-mentor «ти»; моделі = Claude Haiku (L2) / Sonnet (L3); re-permission carrot = free tokens / Premium-trial.

Канали

Канал	Транспорт	Обмеження
Email	ESP за swappable-інтерфейсом (критерії: pre-warmed IPs, feedback loops, one-click unsubscribe; клас Brevo/MailerSend; SES — fallback). Окремий sending-домен (напр. `news.abitly.org`), відокремлений від транзакційного SMTP.	warm-up; SPF/DKIM/DMARC; bounce/complaint < поріг
Telegram	Наявний `@abitlybot` як throttled broadcaster	тільки користувачі, що стартували бота; inline opt-out; ~30 msg/s

Дані

Схема marketing (shared RDS, ADR-2) — операційний стан: read-model контактів (синк SELECT з abitly), сегменти, визначення кампаній, згода, suppression, статус відправки, атрибуція.
Lake-house (analytics) — високооб’ємні engagement-події (sent/delivered/opened/clicked/bounced/complained), AI-логи, marts для атрибуції.
Grounding-джерела (read-only): abitly (offers контакта, NMT-профіль), Strapi (дедлайни, дні відкритих дверей, прохідні бали, ціни).

Персоналізація (AI)

Сегмент = lifecycle stage × intent cluster (напр. «сплячий проспект × медицина»).
L2 — AI генерує копію на сегмент (десятки генерацій, проходять approval queue).
L3 — per-contact для high-value тригерів («дедлайн через 3 дні по offer, який ти моніториш») через попередньо схвалені шаблони з grounded-слотами.
Fact-merge boundary (ADR-3): модель отримує факти як structured input і не може ввести число/дату/назву поза ним; валідатор повертає на регенерацію.

Безпека та комплаєнс

Згода first-class (джерело + час + скоуп); реєстраційна ≠ маркетингова → v1 через re-permission.
Преференс-центр + one-click unsubscribe у кожному листі.
Suppression (unsubscribed / bounced / complained), frequency cap, quiet hours.
Окремий sending-домен захищає транзакційну репутацію.

Вимірювання

campaign_id + contact_id на кожній відправці → UTM на лінках → кліки/конверсії в lake-house → Monobank webhook фіксує last-touch campaign_id → mart join sends → clicks → purchases = attributed revenue (D1).

Фази впровадження

Фаза 0 — фундамент: схема marketing, read-model синк, identity-resolution, преференс-центр, ESP + домен + warm-up, list hygiene.
Фаза 1 — re-permission: win-back кампанія (збір згоди + свіжий інтент), email + Telegram.
Фаза 2 — сегментовані продажі: L2 AI-копія на lifecycle × intent, approval queue, attribution.
Фаза 3 — L3 тригери: deadline-driven per-contact (proto-journey на BullMQ).
Фаза 4 — Journeys (v2): event-triggered сценарії, send-time / next-best-offer (L4), коли назбираються engagement-дані.

Репозиторій та рантайм (план)


Репо	`TODO:` `abitly-org/abitly-marketing` (запропоновано)
Стек (запропоновано)	NestJS + BullMQ (консистентно з API) · ESP SDK · Anthropic SDK (Claude)
Хостинг	`TODO:` AWS ECS Fargate (патерн як API)
Деплой	`TODO:` CodePipeline (патерн як API)

Env-змінні (план, лише назви)

Змінна	Призначення
`MARKETING_DB_SCHEMA`	схема `marketing` у `abitly_prod_db`
`ESP_PROVIDER`, `ESP_API_KEY`, `SENDING_DOMAIN`	доставка email
`ANTHROPIC_API_KEY`, `AI_MODEL_L2`, `AI_MODEL_L3`	AI-генерація
`TELEGRAM_BOT_TOKEN`	reuse бота для Telegram-розсилок
`PREFERENCE_CENTER_URL`, `UNSUBSCRIBE_SECRET`	згода / відписка
`LAKEHOUSE_COLLECTOR_URL`	engagement-події → lake-house

Повний індекс — environments.

Залежності

Залежить від: Postgres (marketing + read abitly) · Valkey (BullMQ) · Strapi (facts) · Analytics lake-house · Telegram bot · ESP (зовнішній) · Anthropic Claude (зовнішній) · Monobank (атрибуція)
Від нього залежать: —

Відкриті питання (TODO)

Фіналізувати ESP (Brevo / MailerSend / SES).
Частка з 5k Telegram-контактів, лінкованих до email-BaseUser (визначає обсяг identity-resolution).
Юридичний review формулювань re-permission (ЗУ «Про захист персональних даних»).
Пороги frequency cap (email / Telegram на тиждень).
Чи виносити marketing write-load на окрему інстанцію (тригер перегляду ADR-2).

Типові проблеми (передбачувані)

Листи в спам → warm-up / SPF / DKIM / DMARC, bounce/complaint rate (email-analytics).
Telegram 429 / бан → throttle, тільки opted-in, inline opt-out.
Marketing навантажує prod RDS → переконатися, що engagement-події йдуть у lake-house, не в RDS (ADR-2).