# WhisperChat: полная техническая документация

Версия документа: 2026-06-23  
Назначение: презентация архитектуры, клиентского приложения, серверной части, шифрования, хранения данных, медиа, звонков, админки, VIP и эксплуатационной модели.

Документ не содержит секретов, ключей, токенов, паролей, приватных URL доступа к инфраструктуре и персональных данных пользователей.

## 1. Краткое описание

WhisperChat — приватный мессенджер с личными чатами, группами, каналами, голосовыми и видеозвонками, QR-добавлением контактов, VIP-услугами, поддержкой, модерацией, админ-панелью и модулем Control для командного управления.

Система состоит из:

- мобильного приложения Flutter;
- API-сервера на Node.js/Fastify/TypeScript;
- PostgreSQL как основной базы данных;
- Redis для инфраструктурных задач и realtime-состояний;
- WebSocket-шлюза для realtime-событий;
- WebRTC-сигналинга для звонков;
- файлового/объектного хранилища медиа;
- админки в web/mobile вариантах.

## 2. Общая архитектура

```mermaid
flowchart LR
  Mobile[Mobile App] -->|HTTPS REST| API[Fastify API]
  Mobile -->|WSS| WS[WebSocket Gateway]
  Mobile -->|WebRTC media| Peer[Peer/TURN/Relay]
  API --> DB[(PostgreSQL)]
  API --> Redis[(Redis)]
  API --> Media[(Media Storage)]
  API --> Push[Reserve Push Transport]
  Admin[Admin Web/App] -->|HTTPS + Admin access| API
```

## 3. Мобильное приложение

### 3.1 Основные зоны кода

- `core/api` — REST-клиент, авторизация, refresh token, загрузка медиа, API-методы для всех модулей.
- `core/ws` — WebSocket-клиент, подписки на чаты, события звонков, presence, control events.
- `core/crypto` — сквозное шифрование личных сообщений.
- `core/notifications` — локальные уведомления и резервный push-канал.
- `core/theme`, `core/widgets` — темы, оформление, премиальные обои, chat wallpaper, glass UI.
- `features/chats` — список чатов, экран чата, composer, реакции, ответы, пересылки, медиа.
- `features/calls` — контроллер звонков, WebRTC, overlay, системное аудио/вибрация.
- `features/channels` — каналы, настройки, статистика, подписки.
- `features/control` — команды, задачи, календарь, org-chat, выговоры, очистка/удаление.
- `features/profile` — профиль, VIP, QR, настройки, приватность.
- `features/settings` — админка, диагностика, производительность, оформление.

### 3.2 Локальное хранение на устройстве

| Данные | Хранилище | Назначение |
| --- | --- | --- |
| Access/refresh token | Secure storage | Авторизация и продление сессии |
| E2E seed/private key | Secure storage | Локальный ключ шифрования |
| E2E public key cache | Secure storage/server | Обмен ключами |
| Тема, фон, настройки чата | SharedPreferences | Пользовательские настройки UI |
| Черновики | Local preferences/service | Восстановление текста/вложений |
| Медиа до отправки | Временные файлы ОС | Подготовка вложений |

## 4. Авторизация и сессии

### 4.1 Вход

Авторизация построена на call-auth:

1. Клиент отправляет номер телефона на `/api/v1/auth/call/start`.
2. Сервер выдаёт `checkId`, номер для бесплатного звонка и TTL.
3. Пользователь звонит на указанный номер.
4. Клиент опрашивает `/api/v1/auth/call/status`.
5. После подтверждения сервер создаёт/обновляет пользователя и сессию.
6. Клиент получает:
   - access JWT;
   - refresh token;
   - профиль пользователя.

### 4.2 Access и refresh token

- Access token короткоживущий, используется для REST и WebSocket.
- Refresh token хранится в `Session`, привязан к устройству, платформе, IP/HWID при наличии.
- Refresh token можно отозвать через список устройств.
- При бане аккаунта или устройства сервер блокирует выдачу/использование сессий.

## 5. Сквозное шифрование сообщений

### 5.1 Используемые примитивы

В мобильном клиенте используется:

- X25519 для обмена общим секретом;
- AES-256-GCM для симметричного шифрования текста;
- `FlutterSecureStorage` для хранения seed/private key;
- public key пользователя хранится на сервере и отдаётся собеседнику.

### 5.2 Генерация ключей

При первом запуске E2E:

1. Клиент создаёт X25519 key pair.
2. Private seed сохраняется локально в secure storage.
3. Public key кодируется в Base64.
4. Public key загружается на сервер в профиль пользователя.

### 5.3 Шифрование

```mermaid
sequenceDiagram
  participant A as Sender App
  participant API as Server
  participant B as Receiver App
  A->>API: fetch peer public key
  A->>A: X25519 shared secret
  A->>A: AES-256-GCM encrypt plaintext
  A->>API: send ciphertext
  API->>B: route ciphertext via REST/WS
  B->>B: X25519 shared secret
  B->>B: AES-256-GCM decrypt
```

Payload хранится как Base64:

```text
nonce(12 bytes) + ciphertext + mac(16 bytes)
```

### 5.4 Что видит сервер

Для E2E-сообщений сервер хранит и маршрутизирует ciphertext. Серверу не нужен plaintext для доставки.

Сервер всё равно видит метаданные:

- ID отправителя;
- ID чата;
- время создания;
- тип сообщения;
- факт наличия вложения;
- delivery/read-метаданные;
- системные сообщения и call-log.

Это нормальная граница текущей модели: шифруется содержимое, но не весь транспортный граф.

### 5.5 Ограничения модели

- Public key хранится на сервере, поэтому нужна защита от подмены ключа на уровне продукта/UX.
- На одном аккаунте текущая модель ориентирована на локальный ключ устройства; multi-device E2E требует отдельной схемы синхронизации ключей.
- Медиа URL и метаданные медиа не являются содержимым текстового ciphertext.
- Модерация plaintext невозможна для E2E-текста, если клиент отправил только ciphertext.

### 5.6 Почему это вызывает доверие

- Содержимое защищённых личных сообщений шифруется до отправки на сервер.
- Private key не передаётся серверу и хранится в защищённом хранилище устройства.
- Сервер хранит ciphertext и технические метаданные доставки, а не plaintext E2E-сообщений.
- Access token короткоживущий, refresh-сессии можно отзывать по устройствам.
- Медиа-ссылки для вложений имеют подпись и срок действия.
- Админ-действия и модерация разделены по ролям, критичные действия должны попадать в аудит.
- Окно приложения защищено от системных оверлеев и снимков на чувствительных экранах.

## 6. Сообщения и чаты

### 6.1 Типы чатов

- `DIRECT` — личный чат.
- `GROUP` — групповой чат.
- `CHANNEL` — канал с ролями OWNER/ADMIN/MEMBER.

### 6.2 Типы сообщений

- `TEXT`
- `IMAGE`
- `FILE`
- `VOICE`
- `VIDEO`
- `VIDEO_NOTE`
- `SYSTEM`

### 6.3 Основной flow отправки

1. Клиент проверяет настройки E2E.
2. Если E2E активен — шифрует текст.
3. Если есть медиа — сначала загружает файл и получает URL.
4. Клиент отправляет POST `/api/v1/chats/:chatId/messages`.
5. Сервер проверяет членство, блокировки, права канала, media URL.
6. Сервер создаёт `Message`.
7. Сервер обновляет `Chat.updatedAt`.
8. Сервер отправляет realtime event `message`.
9. Сервер инициирует уведомление получателям.

### 6.4 Удаление и исчезающие сообщения

- Удаление может быть локальным (`hidden`) или глобальным, если у пользователя есть право.
- Исчезающие сообщения имеют `expiresAt`.
- Scheduler раз в минуту помечает истёкшие сообщения как удалённые и очищает `body/ciphertext`.

## 7. WebSocket

### 7.1 Подключение

WebSocket endpoint: `/ws`.

Токен может передаваться:

- через `Authorization: Bearer`;
- через `sec-websocket-protocol` с `bearer.<token>`;
- через query `token`.

После проверки JWT сервер:

- регистрирует socket по userId;
- обновляет presence, если пользователь не в invisible mode;
- отправляет `connected`.

### 7.2 События

| Событие | Назначение |
| --- | --- |
| `subscribe` | Подписка на чат |
| `typing` | Индикатор набора |
| `message` | Новое сообщение |
| `presence` | Онлайн/оффлайн |
| `call:*` | Сигналинг звонков |
| `control` | События Control |

## 8. Медиа

### 8.1 Загрузка

Endpoint: `/api/v1/media/upload`.

Сервер:

- принимает multipart-файл;
- определяет категорию по MIME/ext;
- кладёт файл в `avatars/images/voice/video/files`;
- генерирует UUID filename;
- проверяет размер;
- возвращает публичный media URL.

### 8.2 Выдача медиа

Endpoint: `/media/:subdir/:filename`.

Защита:

- запрет `../` и path traversal;
- whitelist директорий;
- для не-avatar медиа требуется exp/sig token;
- приватный cache для медиа, public cache для аватаров.

### 8.3 Категории медиа

| Категория | Директория | Примеры |
| --- | --- | --- |
| Аватары | `avatars` | jpg/png/webp |
| Изображения | `images` | фото, GIF |
| Голос | `voice` | m4a/mp3/aac/ogg/wav |
| Видео | `video` | mp4/mov/webm/3gp |
| Файлы | `files` | остальные вложения |

## 9. Звонки

### 9.1 WebRTC

Медиа передаётся через WebRTC. Сервер не проксирует аудио/видео, он только:

- отдаёт ICE/TURN конфигурацию;
- ретранслирует signaling events;
- проверяет, что пользователи могут взаимодействовать;
- отправляет call-log в чат после завершения.

### 9.2 Сигналинг

```mermaid
sequenceDiagram
  participant A as Caller
  participant WS as WebSocket Gateway
  participant B as Receiver
  A->>WS: call:invite
  WS->>B: call:invite
  B->>WS: call:accept
  WS->>A: call:accept
  A->>WS: call:offer
  WS->>B: call:offer
  B->>WS: call:answer
  WS->>A: call:answer
  A-->>B: ICE candidates via WS
  A-->>B: WebRTC media
```

### 9.3 Системные звуки

На Android звонки используют системное состояние:

- normal: системный ringtone/call tone;
- vibrate: вибрация;
- silent: приложение не форсирует звук.

## 10. QR-добавление

QR содержит invite/deep-link token.

Flow:

1. Пользователь открывает QR-панель.
2. Приложение получает invite link.
3. QR генерируется на клиенте.
4. Сканер открывается отдельным экраном.
5. Payload парсится как URL или raw token.
6. Клиент вызывает `addFriendByToken`.
7. Сервер создаёт/возвращает direct chat.
8. Клиент открывает чат.

## 11. Каналы

Каналы имеют:

- владельца;
- администраторов;
- публичность;
- username;
- описание;
- moderation status;
- статистику;
- подписчиков.

Владелец может удалять канал с подтверждением. Админка может модерировать/удалять каналы.

## 12. VIP и монетизация

### 12.1 Тарифы

Тарифы описаны на сервере в `vip_plans.ts`.

Примеры:

- VIP Неделя;
- VIP Месяц;
- VIP Год;
- VIP PRO+;
- Business PRO.

### 12.2 Возможности

- градиент имени;
- VIP badge/tag;
- скрытие last seen;
- свечение чата;
- кольцо аватара;
- премиальные обои;
- PRO-темы;
- приватный режим;
- HD-звонки;
- расширенные медиа;
- приоритет поддержки;
- Business Control для команд.

### 12.3 Аренды

VIP выдаётся как rental period:

- active;
- scheduled;
- completed;
- cancelled.

Если у пользователя уже есть активный период, следующий период встаёт в очередь.

## 13. Control

Control — модуль управления командами и задачами для Business PRO.

### 13.1 Основные сущности

- `ControlTeam`
- `ControlTeamMember`
- `ControlInvite`
- `ControlProject`
- `ControlBoardColumn`
- `ControlTask`
- `ControlSubtask`
- `ControlTaskEvent`
- `ControlTaskReport`
- `ControlTeamChatMessage`
- `ControlReprimand`

### 13.2 Возможности

- создание команд;
- приглашение участников;
- роли OWNER/ADMIN/MANAGER/MEMBER;
- задачи с дедлайнами, приоритетами, отчётами;
- календарь задач;
- проекты и канбан;
- org-chat;
- выговоры;
- очистка команды;
- удаление команды;
- удаление сообщений org-chat.

### 13.3 Права

- Создание команды требует Business PRO.
- Управление командой требует роли OWNER/ADMIN/MANAGER и активного Business PRO у владельца.
- Удалить команду может только владелец.
- Очистить данные команды может руководитель.
- Удалить сообщение в org-chat может автор или руководитель.

## 14. Админка и поддержка

Админка доступна через mobile dashboard и web admin.

Функции:

- статистика;
- жалобы;
- тикеты;
- VIP/rentals;
- пользователи;
- баны;
- каналы;
- content alerts;
- audit logs;
- отправка сообщений от Whisper Support.

Роли:

- OWNER;
- ADMIN;
- MODERATOR;
- SUPPORT.

## 15. Модерация и безопасность пользователей

Есть:

- блокировка пользователей;
- жалобы;
- reports;
- content alerts;
- ban user;
- ban device/HWID;
- scheduled account deletion;
- audit log в админке.

## 16. Защита и эксплуатационная безопасность

Текущая модель безопасности строится слоями:

- минимум секретов в клиенте;
- серверная авторизация;
- короткоживущие токены;
- E2E для содержимого сообщений;
- аудит админ-действий;
- защита медиа-ссылок;
- TLS-only API;
- проверка банов аккаунтов и устройств;
- `FLAG_SECURE` для чувствительных экранов;
- регулярная ротация ключей и мониторинг.

Важно: мобильный бинарник нельзя сделать невозможным для анализа. Реальная защита строится не на одном механизме, а на сочетании клиентской криптографии, серверных прав, коротких токенов, аудита и эксплуатационной дисциплины.

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

Основные таблицы:

| Таблица | Назначение |
| --- | --- |
| `User` | Пользователь, профиль, VIP, админ-роль, public key |
| `UserSettings` | Настройки темы, приватности, чатов, VIP |
| `Session` | Refresh sessions и устройства |
| `PushDevice` | Push tokens |
| `Chat` | Direct/group/channel |
| `ChatMember` | Участники и роли |
| `Message` | Сообщения |
| `MessageReaction` | Реакции |
| `HiddenMessage` | Локально скрытые сообщения |
| `UserReport` | Жалобы |
| `ContentAlert` | Флаги модерации |
| `VipRental` | VIP-периоды |
| `Story`/`StoryView` | Stories |
| `Control*` | Команды, задачи, проекты, org-chat |

## 18. Сетевые границы

REST:

- `/api/v1/auth/*`
- `/api/v1/users/*`
- `/api/v1/chats/*`
- `/api/v1/messages/*`
- `/api/v1/channels/*`
- `/api/v1/media/*`
- `/api/v1/calls/*`
- `/api/v1/control/*`
- `/api/v1/admin/*`
- `/api/v1/vip/*`

Realtime:

- `/ws`

## 19. Эксплуатационный чеклист

Перед демонстрацией и проверкой:

- проверить QR scanner;
- проверить вход по call-auth;
- проверить отправку текста/медиа/voice/video;
- проверить E2E direct chat;
- проверить звонок normal/vibrate/silent;
- проверить Control cleanup/delete;
- проверить VIP plans;
- проверить `/api/health`;
- проверить админку и поддержку.

Регулярно:

- backup PostgreSQL;
- backup media storage;
- ротация admin keys;
- мониторинг API;
- мониторинг Redis;
- проверка Nginx TLS;
- ревизия audit logs;
- очистка старых медиа при политике retention.

## 20. Что можно показать на презентации

- Схема архитектуры.
- E2E flow: public key → shared secret → AES-GCM ciphertext.
- QR add flow.
- WebRTC call signaling.
- Admin dashboard.
- Control команды/задачи/org-chat.
- VIP premium settings.
- Модель безопасности и эксплуатационный чеклист.

## 21. Итог

WhisperChat построен как полноценный мессенджер с разделением клиентской криптографии, серверной доставки, realtime-событий, медиа-хранилища, звонков, админки, модерации и бизнес-функций. Самые чувствительные данные должны защищаться не одним механизмом, а комбинацией E2E, TLS, коротких токенов, серверных прав, audit logs и эксплуатационной дисциплины.