# Архитектура сервиса: компоненты и связки

Документ основан на зафиксированных решениях:

* Custody: omnibus у custody-вендора (hot/warm/cold split).
* Поддержка: 1–2 оператора, Telegram + email + CRM + AI-агент.
* Хостинг: свой VPS в KG/РФ (продолжение линии существующей инфраструктуры).
* СБП-часть не входит в объём (интегрируется как готовый модуль).

Upstream-карточный процессинг — SquareFi или UPay (см. файл 39).

***

### 1. Карта компонентов верхнего уровня

```
┌─────────────────────────────────────────────────────────────────┐
│                    КЛИЕНТСКИЙ СЛОЙ                              │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐    │
│  │   Landing    │  │  TG Bot +    │  │  TG Support Bot     │    │
│  │  (Next.js)   │  │  Mini App    │  │  (live-agent + AI)  │    │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬──────────┘    │
│         │ HTTPS           │ Bot API             │ Bot API       │
└─────────┼─────────────────┼─────────────────────┼───────────────┘
          │                 │                     │
          ▼                 ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                  API GATEWAY (nginx + rate-limit)               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
       ┌───────────────────┼───────────────────┬─────────────────┐
       ▼                   ▼                   ▼                 ▼
┌────────────┐     ┌───────────────┐   ┌──────────────┐   ┌────────────┐
│  Core API  │     │  Webhook      │   │  Support API │   │  Admin API │
│  (FastAPI) │     │  Ingestor     │   │  (CRM-bridge)│   │  (internal)│
└─────┬──────┘     └───────┬───────┘   └──────┬───────┘   └─────┬──────┘
      │                    │                  │                 │
      └────────────┬───────┴──────────────────┴─────────────────┘
                   ▼
         ┌──────────────────────────────────────────┐
         │           СЕРВИСНЫЙ СЛОЙ                 │
         │  user-svc | card-svc | wallet-svc |      │
         │  kyc-svc  | ledger   | notif-svc  |      │
         │  referral | risk-svc | audit-svc         │
         └───────────────┬──────────────────────────┘
                         ▼
         ┌──────────────────────────────────────────┐
         │               СТОРОНА ХРАНЕНИЯ           │
         │  PostgreSQL (OLTP, партиционированный)   │
         │  Redis (кэш, сессии, очереди)            │
         │  ClickHouse (analytics, BI)              │
         │  S3-compatible (документы KYC, экспорты) │
         │  Vault (secrets, API keys, HSM-proxy)    │
         └──────────────────────────────────────────┘

         ┌──────────────────────────────────────────┐
         │             ВНЕШНИЕ ИНТЕГРАЦИИ           │
         │  SquareFi / UPay (card issuing)          │
         │  Fireblocks / BitGo (custody MPC)        │
         │  СБП-модуль (готовый, чёрный ящик)       │
         │  SMS / email / push (Twilio, SendGrid)   │
         │  AML/sanctions (Sumsub, ComplyCube)      │
         │  CRM (Chatwoot self-hosted)              │
         └──────────────────────────────────────────┘
```

***

### 2. Telegram Mini App (основной клиентский интерфейс)

#### 2.1 Технологический стек

| Компонент        | Выбор                                              | Обоснование                                                        |
| ---------------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| Бот-рантайм      | Python 3.11 + aiogram 3.x                          | Совместимо с существующим Python-стеком квант-инфраструктуры       |
| Mini App фронт   | Next.js 14 + TypeScript + Tailwind + Framer Motion | Тот же стек, что на лендинге — единая сборка, общий дизайн-система |
| State management | Zustand + React Query                              | Лёгкий, совместим с Telegram WebApp API                            |
| SDK              | `@telegram-apps/sdk` или `@twa-dev/sdk`            | Официальная обвязка Telegram WebApp API                            |
| Хостинг Mini App | Тот же VPS, субдомен `app.domain`                  | Статика отдаётся с nginx, кеш через Cloudflare CDN                 |

#### 2.2 Авторизация

Telegram Mini App выдаёт `initData` — подписанный ботом токен с информацией о пользователе.

Флоу:

1. Mini App получает `window.Telegram.WebApp.initData` (HMAC-SHA256, подпись ботом).
2. Отправляет в наш Core API: `POST /auth/telegram` с заголовком `X-Telegram-Init-Data`.
3. Сервер валидирует подпись через секрет бота (алгоритм из [Telegram docs](https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app)).
4. Если валидно — выдаём пару JWT: `access_token` (15 мин) + `refresh_token` (30 дней, в httpOnly cookie или Telegram CloudStorage).
5. Для чувствительных операций (выпуск карты, смена лимитов) — второй фактор через Telegram passcode или biometric (`BiometricManager API`).

#### 2.3 Функциональные экраны (согласовано с файлом 38)

* Dashboard (баланс + карусель карт + быстрые действия)
* Cards (список, выпуск, заморозка, sensitive-данные)
* Top-up (  СБП )
* Transactions (история + фильтры + экспорт)
* Profile + KYC + 2FA
* Referral
* Support (entry point → поддержка-бот)

#### 2.4 Критические вопросы для Telegram-специфики

* **initData живёт 24 часа** — требует refresh-потока.
* **CloudStorage** — удобно для хранения неконфиденциальных preference, но не для токенов (есть ограничения по размеру и возможность потери).
* **Haptic feedback и MainButton** — использовать для критичных CTA (выпустить карту, подтвердить перевод).

***

### 3. Telegram Support Bot + CRM + AI-агент

#### 3.1 CRM: выбор под 1–2 операторов

Матрица по требованиям «лёгкая команда + Telegram + email + AI-агент + low cost»:

| CRM                        | Pro                                                                                                                                                       | Contra                                                              | Вердикт       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------- |
| **Chatwoot (self-hosted)** | Open-source, бесплатный, Telegram-коннектор из коробки, email, API, webhook, Rails-стек. Self-host на нашем VPS. Нативная поддержка AI-агентов через API. | Нужен Redis + PostgreSQL, DevOps-overhead на обновления.            | ✅ Рекомендую  |
| Intercom                   | Лучший UX, AI Fin-agent встроен                                                                                                                           | Дорого ($74+ за оператора, +AI $0.99 за resolution), vendor lock-in | Нет           |
| Freshdesk                  | Дешевле Intercom, Telegram через плагин                                                                                                                   | Плагинный Telegram-коннектор работает нестабильно                   | Нет           |
| HelpScout                  | Отличный email, minimal UI                                                                                                                                | Нет Telegram из коробки                                             | Нет           |
| Usedesk (ru-рынок)         | Хорошая локализация, Telegram встроен                                                                                                                     | Русский вендор, вопросы с санкциями при работе с EU                 | Нет           |
| Re:amaze                   | Лёгкий, Telegram есть                                                                                                                                     | Дорого для 1–2 человек                                              | Нет           |
| Самопис                    | Полный контроль                                                                                                                                           | Время разработки, нет готовых отчётов                               | Нет на старте |

**Решение: Chatwoot self-hosted.**

* Docker-образ, разворачивается за час.
* Telegram-коннектор принимает сообщения бота поддержки, email — через IMAP/SMTP.
* API + webhook — можно подключить AI-агента как отдельный сервис-слушатель.
* Есть автоматизация (macros, canned responses, SLA reminders).
* Есть knowledge base (для статей FAQ).

#### 3.2 Архитектура поддержки

```
пользователь ──► SupportBot (Telegram) ──► Chatwoot inbox
                                              │
                        ┌────────── webhook ──┤
                        ▼                     ▼
                   AI-agent                 оператор (веб-UI Chatwoot)
                        │                     │
                        └──── draft ──────────┤
                             (suggest)        │
                                              ▼
                                         ответ клиенту ──► Telegram
```

#### 3.3 AI-агент: два режима

**Режим 1: Autoreply (автономный)**

* Срабатывает на типовые вопросы: «как пополнить», «где мой референт», «статус KYC», «где карта», «как снять».
* Классификатор intent → retrieval из knowledge base (Chatwoot articles + наши доки) → генерация ответа.
* Если уверенность < порога (например, 0.75) или вопрос касается денег/карт → эскалация на оператора.

**Режим 2: Copilot (помощник оператору)**

* Подсказывает оператору черновик ответа.
* Подтягивает контекст клиента из БД (баланс, последние транзакции, статус KYC, открытые тикеты).
* Оператор правит и отправляет.

**Стек AI-агента:**

* LLM: OpenAI GPT-4o-mini / Anthropic Claude Haiku (дешево на объёме) + кэш ответов.
* Оркестрация: собственный Python-сервис (FastAPI) + LangChain или LlamaIndex для RAG.
* Векторная БД: **pgvector** расширение в PostgreSQL (не нужна отдельная БД на старте).
* База знаний: статьи Chatwoot (через API) + markdown-доки из git-репозитория.
* Guard-rail: список запрещённых тем (финансовый совет, юридические гарантии, PII-вывод).

#### 3.4 Safety-правила для AI

* Не раскрывать полный PAN, CVV, реквизиты СБП, персональные данные.
* Не обещать срок выпуска карты / решения спора без подтверждения оператора.
* Всегда логировать запрос + ответ в audit-log для последующего аудита.
* Человеческий оператор — единственный, кто может: заморозить карту, изменить лимит, инициировать возврат, закрыть дисп.

#### 3.5 Обязательные интеграции

* Chatwoot ↔ Core API: оператор видит в карточке клиента: UID, email, phone, баланс, открытые карты, статус KYC, последние 10 транзакций.
* Chatwoot ↔ Telegram-боты: один коннектор на основной бот (пассивный), отдельный на support-бот (активный приём).
* Chatwoot ↔ email: IMAP для приёма, SMTP через SendGrid/Mailgun для ответов и транзакционных писем.

***

### 4. Продающий лендинг

#### 4.1 Стек

| Слой      | Выбор                                                                 | Обоснование                              |
| --------- | --------------------------------------------------------------------- | ---------------------------------------- |
| Фронт     | Next.js 14 App Router + TypeScript + Tailwind + Framer Motion + Lenis | Согласовано с файлом 38, SSG/ISR для SEO |
| CMS       | Git + MDX-статьи для блога                                            | Нет vendor-зависимости, быстро           |
| Формы     | React Hook Form + Zod → Core API `/leads`                             | Валидация клиент-сервер                  |
| Аналитика | Plausible (EU, без cookie) + GA4 + серверная через ClickHouse         | Дубль на случай блокировок расширений    |
| A/B тесты | GrowthBook self-hosted или простые feature-flags в БД                 | Бесплатно, полный контроль               |
| Хостинг   | VPS + nginx + Cloudflare (CDN + WAF)                                  | Тот же периметр                          |

#### 4.2 Связь с бэкендом

* Регистрация / заявка на выпуск карты: `POST /leads` → в PostgreSQL таблицу `leads` → уведомление в Chatwoot как новый тикет.
* Реферальные ссылки: `?ref=CODE` → cookie 30 дней → привязка при регистрации.
* Redirect на Telegram Mini App: `https://t.me/ourbot/app?startapp=ref_CODE` — deep link с атрибуцией.

#### 4.3 Критические моменты

* Лендинг = SSG (полностью предсобранный HTML). Никаких SSR-фетчей с чувствительными данными.
* Consent banner (Cookiebot / self-made) для GDPR.
* Separate subdomain (`www.domain`) — не пересекается с `app.domain` и `api.domain`.
* Sitemap + robots + hreflang (RU/EN).

***

### 5. Базы данных

#### 5.1 Основная OLTP: PostgreSQL 16

Один кластер PostgreSQL, несколько схем / partitioned tables:

| Схема           | Таблицы (ключевые)                                                                  | Заметки                                                                                                          |
| --------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `identity`      | users, user\_profiles, sessions, two\_factor, devices                               | Партиционирование не нужно — \~100К строк                                                                        |
| `kyc`           | kyc\_entities, kyc\_documents, kyc\_checks, sanctions\_hits                         | Логи санкционного скрининга                                                                                      |
| `cards`         | cards, cardholders, sub\_accounts, card\_limits, card\_status\_history              | `card_status_history` — append-only                                                                              |
| `transactions`  | transactions, authorizations, clearings, refunds, reversals                         | **Партиционирование по месяцам** (`PARTITION BY RANGE (created_at)`), как в твоём risk-dashboard с `_acc1/_acc2` |
| `wallet`        | crypto\_deposits, fiat\_deposits, withdrawals, exchange\_orders, balance\_snapshots | Баланс — вью поверх append-only ledger                                                                           |
| `ledger`        | entries (double-entry), accounts, account\_types                                    | Классический double-entry: каждая операция — две записи дебет/кредит                                             |
| `referral`      | referrals, referral\_payouts, referral\_codes                                       |                                                                                                                  |
| `notifications` | outbox, delivery\_log                                                               | Паттерн transactional outbox для гарантированной доставки                                                        |
| `crm_bridge`    | chatwoot\_contact\_map, ticket\_events                                              | Маппинг наших UID на Chatwoot contact\_id                                                                        |
| `audit`         | events (append-only), api\_keys\_usage, admin\_actions                              | Immutable логи, отдельная роль на insert-only                                                                    |

Расширения: `pgvector` (для AI-агента RAG), `pg_partman` (автопартиционирование), `pg_stat_statements`, `pgcrypto`.

#### 5.2 Кэш и очереди: Redis 7

* Кэш сессий (JWT blacklist, rate-limit counters).
* Очереди задач через RQ (Python) или Celery + Redis broker.
* Pub/Sub для внутренних событий между сервисами.
* Rate limiter для API (sliding window).

#### 5.3 Аналитика: ClickHouse

Для тяжёлых аналитических запросов (retention, cohort analysis, funnel) без нагрузки на основную БД. Реплицируем данные из PostgreSQL через logical replication + Debezium или простой periodic dump.

На старте — опционально, можно первые 3–6 месяцев работать только на PostgreSQL.

#### 5.4 Document storage: S3-совместимое

* Minio self-hosted на отдельной VM или прямо на VPS.
* Документы KYC (паспорта, селфи) — **шифруются на стороне приложения** (AES-256-GCM, ключ в Vault) до загрузки в S3.
* Экспорты CSV/PDF для клиентов — подписанные URL с TTL 15 мин.
* Backup каталог для pg\_dump.

#### 5.5 Secrets: Vault

* HashiCorp Vault или OpenBao (fork), self-hosted.
* Хранит: API keys SquareFi/UPay, secret Telegram-ботов, SMTP креды, custody API токены, шифровальные ключи S3-уровня.
* Доступ только через service account, с аудит-логом каждого read.

#### 5.6 Принципы

* **Всё что касается денег — append-only.** Никогда не UPDATE строку транзакции, только INSERT новую с новым статусом + линк на предыдущую. Это твой текущий паттерн в квант-стеке, здесь он тоже ключевой.
* **Ежедневные бэкапы** — pg\_dump + WAL-G в S3 + отдельная off-site копия.
* **PITR (point-in-time recovery)** — обязательно для финансовых данных.

***

### 6. Кошельки и custody

#### 6.1 Omnibus-модель

Мы **не храним индивидуальные ключи** по каждому клиенту. Один (или несколько по сетям) omnibus-адрес, в который клиенты пополняют, а внутри наш ledger распределяет балансы.

```
Клиент отправляет USDT на deposit-адрес (уникальный на клиента или с memo)
                    │
                    ▼
          Custody-провайдер (Fireblocks)
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
   hot wallet              warm wallet            cold wallet
   (операционка)          (rebalance buffer)     (долгосрочное хранение)
   1–2% активов             5–10%                  85–95%
```

#### 6.2 Провайдеры custody — матрица

| Провайдер             | Pro                                                                             | Contra                                                                        |
| --------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Fireblocks**        | Рынок-стандарт, MPC-CMP, policy engine, 50+ сетей, insurance, SOC 2 / ISO 27001 | Дорогой (\~$25K/год минимум + pay-per-transaction), договор через продажников |
| **BitGo**             | PCI-подобный SOC2, insurance $250M, хорошая документация                        | Слабее UX для MPC, дороже для малого объёма                                   |
| **Cobo**              | Азиатский рынок, MPC, дешевле                                                   | Меньше известен в EU, слабее банковская интеграция                            |
| **Copper**            | Сильная институциональная репутация, ClearLoop                                  | Только для крупных клиентов                                                   |
| **Ledger Enterprise** | Хорошо для self-custody с HSM                                                   | Требует своих подписантов                                                     |

**Рекомендую Fireblocks** как scheme-стандарт. Альтернатива по цене — **Cobo Custody** (если объём < $5M в месяц).

#### 6.3 Split активов

| Слой | % средств | Хранение                        | Доступ                                          |
| ---- | --------- | ------------------------------- | ----------------------------------------------- |
| Hot  | 1–2%      | Онлайн, в custody               | Автоматический, для обработки топ-апов и выплат |
| Warm | 5–10%     | Custody multi-sig               | Полуавтомат, требует одобрения workflow         |
| Cold | 85–95%    | Custody air-gapped или self-HSM | Только ручное, с multi-sig 2-of-3 или 3-of-5    |

#### 6.4 Rebalance-логика

Cron-задача каждые N часов:

1. Проверить hot-balance.
2. Если > upper\_threshold (например, 3% от total) → двинуть разницу в warm.
3. Если < lower\_threshold (например, 0.5%) → снять из warm в hot.
4. Warm → cold: ежедневно или по триггеру «warm > 15% total».

Все rebalance-операции — через policy engine custody (по лимитам, адресам, whitelist).

#### 6.5 Pay-out флоу (выплата пользователю)

1. Пользователь запрашивает выплату → транзакция в статусе `PENDING_APPROVAL`.
2. Risk-engine проверяет: лимиты, санкционные списки, velocity.
3. Если < авто-лимит (например, $500) и все проверки ОК → автоматический вызов Fireblocks API.
4. Если > лимит → ручное одобрение оператором.
5. Fireblocks отвечает webhook-ом о статусе → обновляем транзакцию.

#### 6.6 Incident-playbook

* Компрометация hot-ключа → policy engine запрещает все out-transactions → ручное расследование → при необходимости migrate to new addresses.
* Всегда есть **сценарий «холодная дверь»** — процедура ручного вывода всех cold-средств в бэкап-custody за 48 часов.

***

### 7. Внешние интеграции — оркестрация

#### 7.1 SquareFi / UPay

* Отдельный микросервис `issuer-adapter`: унифицирует два провайдера за единым внутренним API.
* Почему адаптер: сегодня SquareFi, завтра UPay — чтобы не переписывать core. Плюс легко A/B протестировать.
* Идемпотентность: каждый внешний вызов помечен `external_request_id`, сохранён до ответа, retry при timeout.
* Вебхуки: отдельный endpoint `/webhooks/issuer/{provider}` — валидация подписи → kafka/redis очередь → handler.

#### 7.2 AML / KYC-screening

Если встроенный KYC провайдера (SquareFi или UPay) недостаточен, поверх:

* **Sumsub** — самый распространённый в СНГ и EU, с liveness, OCR, PEP-скрининг.
* **ComplyCube** — дешевле, UK-based.
* **Shufti Pro** — широкое покрытие стран.

Минимум — sanctions screening при каждом деньгопотоке (OFAC, EU, UK, UN списки обновляются).

#### 7.3 Notification-слой

| Канал                     | Провайдер                    | Use-case                                    |
| ------------------------- | ---------------------------- | ------------------------------------------- |
| Telegram push             | Свой бот (бесплатно)         | Транзакции, статусы, 2FA                    |
| Email                     | SendGrid / Mailgun / AWS SES | Квитанции, KYC, маркетинг                   |
| SMS                       | Twilio / SMSC.ru             | 3DS OTP (если SMS-fallback), восстановление |
| In-app push (iOS/Android) | Firebase FCM + APNs          | Будущие нативные приложения                 |

Паттерн transactional outbox: сервис пишет в таблицу `notifications.outbox` → отдельный воркер отправляет → гарантированная доставка при сбоях.

***

### 8. Безопасность: сквозная

* WAF (Cloudflare) перед всеми публичными endpoint-ами.
* mTLS внутри между сервисами (сертификаты из Vault, ротация раз в N дней).
* Secrets никогда не в env-переменных докер-образа — только из Vault через sidecar.
* Все PII (паспорт, адрес, телефон) — в отдельной таблице с шифрованием на уровне столбца (`pgcrypto` + ключ в Vault).
* PCI-scope минимизируем: PAN/CVV от SquareFi/UPay **не сохраняем у себя** — всегда fetch по запросу из sensitive-endpoint и сразу передаём в Mini App через короткоживущий токен.
* Audit log каждого админ-действия (доступ к PII, изменение лимита, вывод средств).
* Логи бэкапятся в отдельный S3-bucket с immutable lock (compliance-требование).

***

### 9. DevOps на нашем VPS

#### 9.1 Стек

* **Docker Compose** на старте (как уже у тебя работает на 144.124.x.x).
* Переход на **Kubernetes (k3s single-node)** при росте нагрузки — сохраняет тот же VPS, но даёт декларативные деплои.
* CI/CD: **GitHub Actions** или **Gitea + Drone CI** self-hosted.
* Registry: локальный Harbor или GitHub Container Registry.

#### 9.2 Мониторинг

* Metrics: **Prometheus + Grafana** (как в твоём квант-сетапе).
* Logs: **Loki + Grafana**.
* Traces: **Tempo** + OpenTelemetry SDK в сервисах.
* Alerting: **Alertmanager** → Telegram-канал для разработки + PagerDuty для критичных.

#### 9.3 Резервное копирование и DR

* pg\_dump ежедневно + WAL-G для point-in-time recovery.
* 3-2-1: 3 копии (локально + S3 + off-site), 2 разных носителя, 1 копия off-site.
* RTO-цель: 4 часа. RPO-цель: 15 минут.
* Плановые DR-drill 1 раз в квартал.

#### 9.4 Ограничения VPS-модели (честно)

Свой VPS даёт контроль и низкую цену, но:

* Нет managed PostgreSQL — бэкапы, апгрейды, тюнинг лежат на тебе.
* Если VPS упал — весь сервис недоступен. Нужен хотя бы failover на 2 VPS в разных датацентрах при росте.
* PCI DSS: держать там sensitive card data — нельзя. Но так как мы не храним PAN, это не блокер.
* GDPR: расположение VPS (KG/РФ) — нужно явно указывать в политике конфиденциальности + заключать DPA при обработке данных EU-граждан.

***

### 10. Что ещё критично, но не попало в твой список

1. **Risk-engine** — отдельный сервис, который решает: одобрить ли транзакцию / выпуск карты / вывод. Velocity-checks, сумма, гео, MCC. Не путать с custody policy engine.
2. **Ledger как первое гражданство** — двойная запись для всех денежных операций. Это не просто таблица, это сервис с инвариантами (сумма дебетов = сумма кредитов).
3. **Feature-flags и config service** — чтобы раскатывать фичи на сегменты без деплоя.
4. **Status page** (статус-страница) — для публичного отображения инцидентов. Снижает нагрузку на поддержку.
5. **Reconciliation** — ежедневная сверка нашего ledger с остатками у SquareFi/UPay и у custody. Если разошлось — немедленный alert.
6. **Dispute-workflow** (даже если у провайдера нет API) — хотя бы внутренний, где оператор ведёт спор в Chatwoot и фиксирует статус у нас.
7. **Legal-compliance journal** — кто получил доступ к каким данным клиента, для GDPR Article 15 запросов.
8. **BI-дашборды для основателей** — Metabase или Superset поверх ClickHouse. DAU, MAU, retention, avg. transaction, LTV.

***

### 11. Итоговая схема потоков данных

#### 11.1 Выпуск карты

```
Mini App ─► Core API (/cards) ─► kyc-svc (проверка статуса)
                                       │
                                       ▼
                                 card-svc ─► issuer-adapter ─► SquareFi
                                                                   │
                                                                   ▼
                                                              webhook ISSUING/CARD/CREATED
                                                                   │
                                  ┌────────────────────────────────┘
                                  ▼
                           card-svc (UPDATE cards SET status=ACTIVE)
                                  │
                                  ▼
                           notif-svc ─► Telegram push «Карта выпущена»
```

#### 11.2 Транзакция клиента

```
Merchant ─► SquareFi (auth) ─► webhook CARD_TRANSACTION/AUTHORIZATION
                                        │
                                        ▼
                                 webhook-ingestor (валидация подписи)
                                        │
                                        ▼
                                 kafka/redis queue
                                        │
                                        ▼
                                 transactions-svc:
                                   1. INSERT authorization
                                   2. INSERT ledger entries (debit + credit)
                                   3. UPDATE balance view
                                        │
                                        ▼
                                 notif-svc ─► Telegram push «$45 Starbucks»
```

#### 11.3 Крипто-депозит

```
Клиент отправляет USDT ─► deposit-адрес (Fireblocks)
                                        │
                                        ▼
                                 Fireblocks webhook (deposit.confirmed)
                                        │
                                        ▼
                                 wallet-svc:
                                   1. INSERT crypto_deposits
                                   2. INSERT ledger entries
                                   3. UPDATE balance
                                        │
                                        ▼
                                 если клиент хочет на карту ─► exchange-svc ─► issuer-adapter ─► recharge карты
```

***

### 12. Порядок запуска (MVP → V1)

**MVP (3–4 месяца)**

1. Telegram Mini App + основной бот (базовые экраны: баланс, выпуск карты, топ-ап, история).
2. Core API на FastAPI.
3. PostgreSQL на том же VPS (как сейчас).
4. Issuer-adapter под одного провайдера (SquareFi или UPay — решить после ответа по push provisioning).
5. Fireblocks (sandbox сначала) для custody.
6. Chatwoot + Telegram support-бот (без AI на первых неделях).
7. Лендинг.

**V1 (+2 месяца)** 8. AI-агент для support (copilot-режим). 9. Risk-engine. 10. Двухпровайдерный adapter (SquareFi + UPay — failover). 11. ClickHouse + BI-дашборды. 12. Reconciliation-сервис. 13. Status page.

**V2 (+3 месяца)** 14. Нативные iOS/Android приложения. 15. Полноценный dispute-workflow. 16. White-label API для B2B. 17. Переезд на k3s, failover-VPS.

***

### 13. Открытые вопросы, которые нужно закрыть до старта разработки

1. **Push provisioning Apple/Google Pay** — не задокументирован у обоих провайдеров. Блокер для заявленного на лендинге функционала. Запросить напрямую.
2. **Договор с custody-провайдером** — минимальный объём, KYC компании, юрисдикция KG-entity.
3. **AML-оператор** — кто отвечает за sanctions screening (мы или провайдер), нужен ли отдельный AML-офицер в штате.
4. **PCI DSS scope** — сертификационный или SAQ A достаточно при условии что PAN не хранится.
5. **Юрисдикция пользователей** — кому выпускаем карты (residency), кому отказываем.
6. **Партнёр по SMS** для России — Twilio может не работать, нужен локальный.
7. **Fallback-сценарий при падении upstream** — что делает сервис, если SquareFi/UPay лежит 4 часа.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alt3-capital.gitbook.io/funding-arbitrage-strategy/cart/dokumentaciya-v0/arkhitektura-servisa-komponenty-i-svyazki.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
