# Happ VPN: White Paper (RU)

## 1) Executive summary

Happ VPN - это VPN SaaS-платформа с control-plane архитектурой, где единый backend управляет авторизацией, биллингом, Telegram-ботом, рефералкой и каталогом пользовательских VPN-нод. Проект уже имеет рабочий MVP-скелет в монорепозитории и ориентирован на быстрый вывод продукта на рынок с последующим усложнением до production-grade уровня.

Цель текущего этапа: подтвердить unit economics, улучшить reliability и превратить MVP в управляемый инвестиционный продукт с прозрачной дорожной картой.

## 2) Проблема и рыночная гипотеза

### Проблема
- Пользователям нужен стабильный доступ к Telegram и обычным сервисам в одном сценарии подключения.
- На рынке много VPN, но часто слабая прозрачность, перегруженный UX и сложная поддержка.
- У операторов VPN высокая операционная сложность: платежи, антифрод, обновления нод, поддержка устройств и retention.

### Гипотеза Happ
- Скомбинировать Telegram-бот + web-кабинет + control-plane API в единую продуктовую воронку.
- Сделать упор не на "магический маркетинг", а на предсказуемую эксплуатацию: биллинг, ежедневная тарификация, ноды, метрики, риски.
- Использовать multi-agent процесс разработки для ускорения итераций по модулям (infra/backend/web/bot).

## 3) Product overview

Happ VPN состоит из:
- **Backend (FastAPI + PostgreSQL)**: auth, billing, webhook, internal jobs, сервисные ручки для Telegram-бота, работа с VPN-нодами.
- **Web (Next.js)**: login, dashboard, plans, devices, setup.
- **Telegram Bot**: вход пользователя, баланс, тарифы, рефералка, устройства, переходы в web.
- **Provisioning script**: `scripts/install_vpn.sh` для первичного bootstrap VPN-ноды через SSH.

## 4) Текущий статус: что уже сделано

Ниже указано только то, что подтверждается кодом/документацией репозитория.

### Реализовано
- **Control plane API** с healthcheck и маршрутизаторами auth/billing/webhooks/internal/bot/vpn/plans.
- **Auth**: Google и Telegram-вход, web-flow подтверждения Telegram-логина через deep link.
- **Billing MVP**:
  - баланс и статус подписки;
  - идемпотентный stub webhook пополнения;
  - ежедневное списание (cron endpoint + billing service).
- **Referral logic**: привязка реферера при регистрации, защита от self-referral, публичный referral code и статистика.
- **VPN nodes API**: регистрация, список, удаление пользовательских нод.
- **Telegram bot**:
  - команды баланса, тарифов, setup, referral, devices;
  - web-login confirmation flow.
- **Web scaffold (Next.js)**: страницы login/dashboard/plans/devices/setup.
- **OpenAPI contract** в `openapi/openapi.yaml`.
- **Инфра-скрипт** `scripts/install_vpn.sh` для установки sing-box на целевую ноду.

### Частично реализовано
- UX и продуктовая глубина web-кабинета (многое еще в scaffold-режиме).
- Device lifecycle automation (пока базовая CRUD-поверхность в API и простая web-страница).
- Операционный контур работы с нодами (bootstrap есть, полноценный orchestration pipeline еще нет).

### Не реализовано (ключевые gaps)
- Реальный платежный провайдер (вместо stub webhook).
- Продвинутая observability (alerts, SLO, централизованные логи/метрики).
- Security hardening полного production-уровня (секреты, ротации, расширенный аудит).
- Масштабирование control-plane (очереди/workers/разделение ролей узлов).
- Полная финансовая и партнерская аналитика (LTV/CAC/cohort/referral payout pipeline).

## 5) Архитектура и поток данных

```mermaid
flowchart TB
  users[Users] --> web[WebCabinet]
  users --> tg[TelegramBot]
  web --> api[FastAPIControlPlane]
  tg --> api
  api --> db[(PostgreSQL)]
  jobs[DailyBillingJob] --> api
  pay[PaymentWebhook] --> api
  api --> nodes[VpnNodesRegistry]
  provision[install_vpn.sh] --> vps[VpnNodeVPS]
```

Принцип: один control-plane координирует бизнес-логику и lifecycle клиента, а VPN-ноды масштабируются отдельно.

## 6) Рыночные референсы и выводы для Happ

Референсы:
- [Proton VPN](https://protonvpn.com/en)
- [NordVPN Features](https://nordvpn.com/features/)
- [IVPN](https://www.ivpn.net/en)
- [Mullvad comparison context](https://stateofsurveillance.org/guides/advanced/vpn-strategy)

Выводы:
- Сильные игроки продают не только "VPN", а **доверие + предсказуемость + UX**.
- Успешные страницы дают четкую структуру: value proposition -> trust -> features -> plans -> CTA.
- Для Happ важно адаптировать эти принципы без копирования дизайна/маркетинговых материалов.

## 7) Go-to-market и метрики

### Фокус 0-12 месяцев
- Telegram-first acquisition + web-conversion.
- Referral как канал органического роста.
- Акцент на retention и качество сервиса, а не только на агрессивный performance marketing.

### Базовые KPI
- Registration -> first payment conversion.
- D7 / D30 retention платящих пользователей.
- ARPPU / MRR динамика.
- Churn rate по причинам (цена, нестабильность, блокировки, UX).
- Доля активных пользователей по регионам нод.

## 8) Риски и mitigation

### Операционные
- Риск смешивания основного бизнеса и VPN-контуров на одном домене/сервере.
- Mitigation: инфраструктурная изоляция, резервные домены, разделение IP и reverse-proxy.

### Технические
- Риск деградации качества при росте нагрузки.
- Mitigation: очередь задач, выделенные workers, мониторинг критичных API.

### Платежные/регуляторные
- Риск блокировок платежных сценариев и требований комплаенса.
- Mitigation: поэтапное подключение провайдеров, юридическая валидация оферт и партнерских условий.

## 9) Дорожная карта развития

### Уже пройдено (MVP foundation)
- M0-M2: базовая архитектура, auth/billing MVP, web/bot scaffold, bootstrap нод.

### Ближайшие этапы
- **M3**: реальные платежи + production webhooks.
- **M4**: углубление Telegram customer flows.
- **M5**: рефералка и аналитика в продуктовых отчетах.
- **M6**: hardening, мониторинг, ротация секретов, эксплуатационная стабильность.

### Post-MVP усложнение
- Распределенные workers и фоновые очереди.
- A/B эксперименты тарифов и onboarding.
- Автоматизация node lifecycle и incident response.

## 10) Multi-agent execution model

Рабочая модель параллельной поставки:
- **Agent A (`infra/install`)**: provisioning и ноды.
- **Agent B (`backend`)**: API, auth, billing, webhooks.
- **Agent C (`web`)**: investor/public + dashboard UX.
- **Agent D (`bot`)**: Telegram-сценарии и связка с API.

Для каждой задачи фиксируются:
- входные артефакты,
- критерий завершения,
- ожидаемый PR-ready результат.

## 11) Заключение

Happ VPN уже имеет валидный технологический каркас и может быть представлен инвестору как проект с прозрачной точкой входа, реалистичной дорожной картой и контролируемыми рисками. Следующая ключевая фаза - переход от MVP-скелета к production-надежности и управляемому росту через метрики.