Information item: Software Architecture Description. Content and viewpoints are informed by ISO/IEC/IEEE 42010 (architecture description) and ISO/IEC/IEEE 15289 (life-cycle information items). User/operator documentation is published separately with reference to ISO/IEC 26514. This wording does not claim certification or verified conformity. Print layout targets A4 for reproducible distribution.
на программное обеспечение «CoronerChat» Версия изделия: 2.7.10 (package.json / GitHub Latest)
Аннотация
К программе (изделию)
CoronerChat 2.7.10 — прикладное программное обеспечение для стримеров и модераторов: объединение чатов Twitch, VK Video Live, Kick, YouTube Live, Rutube, DonationAlerts и MemeAlerts в единую ленту с нормализацией формата сообщений, буфером и поиском; отображение во встроенном веб-интерфейсе и в режиме оверлея OBS; авторизация OAuth 2.0 (где применимо); каталоги эмодзи/бейджей (в т.ч. 7TV); OBS WebSocket; UX-пакет эфира (пресеты, алерты, goal/vote); локальная статистика сессий и достижения; локализация UI (ru/en/ro/de/fi); автообновление с GitHub Latest (dorimeryt-alt/CoronerChat); релей «now playing»; desktop Electron и опциональный zapret. Поставка: NSIS Setup / portable, каталог данных CoronerChat-data.
К настоящему документу
Настоящее техническое описание содержит сведения об архитектуре ПО «CoronerChat»: структурную модель в нотации IDEF0, контекстные и декомпозированные диаграммы потоков данных (DFD), описание взаимодействия с каждой внешней платформой и смежными HTTP-сервисами, перечень хранилищ данных, диаграммы процессов (BPMN) и последовательностей (UML), состав программных модулей, группы маршрутов HTTP и типы сообщений WebSocket, нефункциональные требования и словарь данных; в разделе 1 приведён перечень реализованных функций изделия (п. 1.5). Диаграммы, выполняемые средствами Mermaid в среде браузера, приведены для наглядности и сопровождения кода. Документ предназначен для разработчиков, системных аналитиков и лиц, ответственных за сопровождение комплекта программной документации. Эксплуатационная документация для оператора изложена в docs/coronerchat-operation-print.html и на сайте (docs/guide.html) в соответствии с ISO/IEC 26514.
ISO/IEC/IEEE 42010 — Systems and software engineering — Architecture description.
ISO/IEC/IEEE 15289 — Content of life-cycle information items (software documentation).
ISO/IEC 26514 — Requirements for designers and developers of user documentation.
ISO/IEC 12207 — Software life cycle processes (supply, operation, maintenance).
ISO/IEC 25010 — Systems and software Quality Requirements and Evaluation (SQuaRE).
ISO/IEC 27001 / 27002 — Information security management (controls mapping; see Security statement).
ECMA-262 (JavaScript), WHATWG HTML Living Standard, WebSocket Protocol RFC 6455.
Спецификации внешних систем: Twitch IRC / EventSub / Helix, VK Video Live API, Kick Chat, DonationAlerts, MemeAlerts, YouTube Data API / Google OAuth 2.0, 7TV (по используемым в коде конечным точкам).
Исходный код изделия: каталоги src/server/, src/providers/, src/electron/, package.json.
Термины, определения и сокращения
Термин / сокращ.
Определение
ПО, изделие
Программное обеспечение CoronerChat — сервер чата и UI (веб и Electron).
Открыть в браузере с сетью (Mermaid с CDN). Печать в PDF: Ctrl+P → «Сохранить как PDF». При обрезании диаграмм уменьшите масштаб страницы в предпросмотре.
Содержание
Общие положения; перечень реализованных функций (п. 1.5)
Структурная модель (IDEF0)
Состав программных модулей и соответствие процессам
Контекстная диаграмма потоков данных (DFD, уровень 0)
Диаграмма декомпозиции первого уровня (DFD-1)
Описание взаимодействия с внешними платформами (DFD-2 по каждой платформе)
Хранилища данных
Описание процессов (BPMN)
Диаграммы последовательности взаимодействия
Компоненты и развёртывание
События WebSocket и группы HTTP API
Нефункциональные требования
Словарь данных
Заключение
1. Общие положения
1.1. Назначение изделия
Единый клиент для приёма, нормализации, буферизации и отображения чата с нескольких платформ (Twitch, VK Video Live, Kick, YouTube Live, Rutube, DonationAlerts, MemeAlerts), а также: OAuth, прокси ассетов и каталогов эмодзи (7TV), OBS WebSocket, UX-пакет эфира, локальная статистика и достижения, локализация UI, автообновление с GitHub Latest, релей now playing, опционально zapret на desktop, оверлей и планшетный режим через общий HTTP+WS сервер.
1.2. Назначение документа
Формализация архитектуры для сопровождения, обучения и согласования изменений; договорённость о границах системы и внешних интерфейсах.
1.3. Область применения документа
Разработка, сопровождение и выпуск CoronerChat. Эксплуатация оператором — по docs/coronerchat-operation-print.html и docs/guide.html (ISO/IEC 26514).
1.4. Границы системы
В составе ПО: процесс Node.js (ChatAppServer), встроенный web-ui, провайдеры в src/providers/, при desktop — оболочка Electron.
Вне ПО: внешние платформы (Twitch, VK Video Live, Kick, DonationAlerts, MemeAlerts, YouTube, Rutube, 7TV/CDN), OBS Studio, GitHub Releases (канал обновлений), ОС, браузер пользователя при внешней авторизации, сеть и политики DPI (zapret).
1.5. Перечень реализованных функций изделия
Ниже приведена характеристика реализованного функционала текущей версии CoronerChat: перечень не претендует на исчерпание всех пунктов UI, а фиксирует основные возможности, подтверждаемые кодом сервера и встроенного клиента.
1.5.1. Режимы поставки и запуска
режим web: запуск ядра Node.js, встроенный web-ui по HTTP, WebSocket /ws;
режим desktop: оболочка Electron + Chromium, доступ к локальному серверу ядра;
сборки под Windows: переносимый исполняемый файл, распакованный каталог, установщик NSIS с сохранением пользовательских данных при обновлении (политика инсталлятора).
1.5.2. Приём и объединение чатов нескольких платформ
Twitch: чтение чата по IRC (включая сценарии анонимного просмотра и чтения от имени авторизованного пользователя); параллельно — события баллов канала и Hype Train через EventSub; при ограничениях EventSub — опрос наград через Helix (poller); реконнект и диагностика транспорта в state.twitchTransport;
VK Video Live: приём сообщений по WebSocket API; каталог и прокси бинарных ресурсов;
Kick: приём сообщений чата по WebSocket при заданном канале и токене OAuth;
DonationAlerts: получение событий донатов по HTTP long-poll;
MemeAlerts: подключение к шлюзу по WebSocket с нормализацией JWT из OBS-ссылки; управление connect/disconnect из UI;
YouTube Live: получение сообщений живого чата через YouTube Data API v3 (ключ API или OAuth Google) либо browser-chat режим;
единая точка слияния потоков в ChatAppServer: нормализация сообщений, дедупликация (в т.ч. redemption и hype), ограниченный буфер и история;
рассылка клиентам по WebSocket с типами snapshot, state, chat.message, chat.moderation, chat.annotation и др.;
встроенный web-ui: отображение объединённого чата, настроек, оверлея и планшетного режима, темы и масштабы отображения (см. web-ui.js).
1.5.4. OAuth 2.0 и локальное хранение учётных данных
потоки авторизации для Twitch, VK (включая сценарии с браузером и implicit), Kick, DonationAlerts, YouTube (Google) через маршруты /api/auth/…;
сохранение токенов и параметров сессии в каталоге данных приложения (*-auth.json, app-state.json и др.).
1.5.5. Действия в экосистеме Twitch (при наличии прав доступа токена)
отправка сообщений в чат через Helix Send Chat Message;
модерация: удаление сообщений, таймаут, бан — при наличии соответствующих прав и scopes;
изменение названия и категории трансляции для собственного канала;
поддержка ряда slash-команд из поля ввода (в т.ч. /raid, /announce, /shoutout, настройки скорости чата, shield mode и др. в объёме, реализованном сервером и API).
1.5.6. Прокси HTTP, каталоги эмодзи и бейджей
кэшируемые каталоги и выдача ресурсов 7TV, Twitch (бейджи, эмодзи, клипы и вспомогательные запросы), VK (каталог, asset) — для снижения проблем CORS и единообразного Referrer;
prefetch и health-check для 7TV по маршрутам API изделия.
1.5.7. Интеграции в desktop-сборке
телеметрия OBS Studio через WebSocket плагина;
релей now playing от внешнего источника метаданных трека;
Статистика и достижения: локальная история эфиров, категории/игры, топы чата и донатов, полка достижений в приложении (не в OBS overlay);
i18n: словари src/server/i18n/locales/{ru,en,ro,de,fi}.json, персист uiLocale, POST /api/settings/locale; applyI18nDom без сброса вложенных контролов (2.7.5);
Автообновление: канал dorimeryt-alt/CoronerChat; GET …/releases/latest; установка Setup; skip-версия POST /api/update/dismiss; install POST /api/update/install; отсев legacy-тегов 2.25–2.35.
2. Структурная модель (IDEF0)
Модель приведена в нотации IDEF0 (ICOM). Диаграммы выполнены в виде векторной графики SVG.
2.1. Контекст деятельности A-0
A-0. Агрегировать и показать мультиплатформенный чат и состояние стрима
2.2. Декомпозиция процессов A1–A6
A1. Приём событий от внешних чатов
A2. Нормализация, дедупликация, буфер, модерация
A3. HTTP: UI, REST, статика, прокси ассетов
A4. WebSocket: снимок, поток сообщений, отладка
A5. OBS, now playing, zapret (desktop)
A6. Управление OAuth и сохранение сессий
3. Состав программных модулей и соответствие процессам кодовой базе
Рендер чата, настройки, overlay, WebSocket-клиент на /ws
4. Контекстная диаграмма потоков данных (DFD, уровень 0)
Рисунок 4 — Контекстная DFD: изделие «CoronerChat» и внешние сущности
flowchart TB
subgraph EXT["Внешние сущности"]
U[Пользователь]
TW[Twitch]
VK[VK Video Live]
KI[Kick]
DA[DonationAlerts]
MA[MemeAlerts]
YT[YouTube Live]
S7[7TV и CDN эмодзи]
OB[OBS Studio]
end
P(("P0 Ядро CoronerChat"))
DS[(D Хранилище файлов)]
U <-->|HTTP REST WebSocket| P
P <-->|IRC EventSub Helix| TW
P <-->|WS API| VK
P <-->|WS OAuth| KI
P <-->|HTTP| DA
P <-->|WS token| MA
P <-->|чат| YT
P <-->|HTTP каталоги| S7
P <-->|WS телеметрия| OB
P <-->|read write| DS
flowchart LR
subgraph Stores["Хранилища"]
D1[(app-state и persisted)]
D2[(OAuth токены json)]
D3[(буфер и история в RAM)]
end
P1[1 Источники]
P2[2 Ядро буфера]
P3[3 HTTP]
P4[4 WebSocket]
EXT[Twitch VK Kick DA MA YT]
UI[Браузер UI]
P1 -->|события| P2
P2 --> D3
P2 --> P4
P3 --> D1
P3 --> D2
P3 <-->|запросы| UI
P4 -->|push| UI
EXT <--> P1
6. Описание взаимодействия с внешними платформами (DFD, уровень 2)
Все перечисленные ниже интеграции сходятся в единый процесс A2 — класс ChatAppServer (src/server/chat-app-server.js): нормализация сообщений, дедупликация, messageBuffer, рассылка клиентам по WebSocket. Отличия заключаются во внешнем транспорте, правилах аутентификации и составе типов событий.
6.1. Twitch
Назначение. Приём чата по IRC; дополнительно — события баллов канала и Hype Train через EventSub WebSocket и при необходимости нормализация наград через Helix REST (poller); доступ к API Twitch по OAuth.
Назначение. Приём сообщений и служебных событий трансляции VK Video Live по WebSocket API.
Компонент
Файл
Роль
Источник VK
src/providers/vk/vk-video-live-source.js
WS-клиент, парсинг событий в унифицированные сообщения.
VkAuth
src/providers/vk/vk-auth.js
OAuth / implicit, запись vk-auth.json.
Вспомогательные HTTPS-вызовы
src/providers/vk/vk-https-utils.js
Общие утилиты запросов к API VK.
Внешние интерфейсы. WebSocket и HTTPS API VK Video Live (см. актуальную документацию VK).
HTTP API изделия./api/auth/vk/* (в т.ч. start, poll, logout, callback, implicit-token); GET /api/vk/catalog, GET /api/vk/asset (каталог и прокси бинарных ресурсов).
Состояние.vkTransport (реконнект, время последнего подключения, ошибки сети).
Рисунок 6.2 — DFD-2: VK Video Live → ядро
flowchart LR
VK[VK Video Live WS]
SRC[vk-video-live-source]
A2[ChatAppServer A2]
WS[WebSocket клиенты]
VK -->|события чата| SRC -->|нормализованное сообщение| A2 -->|chat.message| WS
6.3. Kick
Назначение. Приём сообщений чата Kick по WebSocket; отправка сообщений при наличии прав — через REST API Kick.
Компонент
Файл
Роль
KickChatSource
src/providers/kick/kick-chat-source.js
WS чата, интеграция с ядром.
KickAuthController
src/providers/kick/kick-auth.js
OAuth Kick, kick-auth.json.
Kick HTTP
kick-http-public.js, kick-api.js
Публичные данные канала, постинг сообщений.
Внешние интерфейсы. WebSocket чата Kick; HTTPS OAuth и API Kick.
HTTP API изделия./api/auth/kick/*; POST /api/settings/kick (сохранение канала и перезапуск транспорта при необходимости).
Состояние.state.kick, state.kickAuth (снимок авторизации в ответах API).
На рисунке 6.8 показаны все основные источники, формирующие единый поток chat.message после обработки в A2 (детализация ветвления Twitch — на рисунке 6.1).
Наиболее разветвлённый сценарий UI↔сервер; для остальных платформ сохраняется логика «start → внешний браузер или окно → poll → запись json → broadcast state».
Рисунок 8.2 — BPMN: авторизация Twitch
flowchart TB
subgraph U["Дорожка пользователь"]
S([Нужен вход Twitch])
O1[Открыть вкладку авторизации UI]
O2[POST twitch start]
O3[Браузер OAuth окно или redirect]
O4[POST twitch poll по таймеру]
E([Токен в приложении])
S --> O1 --> O2 --> O3 --> O4 --> E
end
subgraph SYS["Дорожка система"]
H1[handleHttp старт URL]
H2[TwitchAuth обмен]
H3[Запись файла токена]
H4[broadcast state]
O2 -.-> H1
H1 --> H2
O4 -.-> H2
H2 --> H3
H3 --> H4
end
8.3. Первое подключение WebSocket клиента
Рисунок 8.3 — BPMN (UML sequence): подключение к /ws
sequenceDiagram
participant C as Клиент UI
participant W as WS сервер
participant S as ChatAppServer
C->>W: connect /ws
W->>S: connection handler
S-->>C: snapshot буфер и состояние
loop Живое
S-->>C: chat.message state …
end
8.4. Установка NSIS (ветвления сценария)
Рисунок 8.4 — BPMN: установщик Windows
flowchart TB
A([Старт Setup])
B{Обновление поверх?}
C[Uninstall старой с KEEP_APP_DATA]
D[Копирование файлов]
E{Есть legacy AppData?}
F[needs-migration.json подсказка]
G[Страница заметок 2.25]
H{Запустить?}
Z([Конец])
A --> B
B -->|да| C --> D
B -->|нет| D
D --> E
E -->|да| F
E -->|нет| G
F --> G
G --> H
H -->|да| Z
H -->|нет| Z
9. Диаграммы последовательности взаимодействия (UML)
sequenceDiagram
participant TW as Twitch EventSub
participant CP as TwitchChannelPointsEventSub
participant S as ChatAppServer
participant W as WS клиенты
TW->>CP: notification redemption
CP->>S: onRedemption ev
S->>S: dedup id handleChannelPointsRedemption
S->>W: chat.message channelPointsRedemption
9.2. VK Video Live — сообщение чата
Рисунок 9.2 — UML sequence: упрощённый поток
sequenceDiagram
participant VK as VK WS
participant SRC as vk-video-live-source
participant S as ChatAppServer
participant W as WS клиенты
VK->>SRC: chat service event
SRC->>S: emit normalized message
S->>W: chat.message
9.3. Kick — сообщение чата
Рисунок 9.3 — UML sequence: упрощённый поток
sequenceDiagram
participant K as Kick WS
participant SRC as kick-chat-source
participant S as ChatAppServer
participant W as WS клиенты
K->>SRC: chat payload
SRC->>S: emit message
S->>W: chat.message
9.4. DonationAlerts — событие long-poll
Рисунок 9.4 — UML sequence: упрощённый поток
sequenceDiagram
participant DA as DonationAlerts HTTPS
participant SRC as donation-alerts-source
participant S as ChatAppServer
participant W as WS клиенты
DA-->>SRC: poll response
SRC->>S: enqueue alert as message
S->>W: chat.message
9.5. MemeAlerts — событие WebSocket
Рисунок 9.5 — UML sequence: упрощённый поток
sequenceDiagram
participant MA as MemeAlerts WS
participant SRC as meme-alerts-source
participant S as ChatAppServer
participant W as WS клиенты
MA->>SRC: alert frame
SRC->>S: emit message
S->>W: chat.message
9.6. YouTube Live — сообщение чата (опрос API)
Рисунок 9.6 — UML sequence: упрощённый поток
sequenceDiagram
participant YT as YouTube Data API
participant SRC as youtube-live-source
participant S as ChatAppServer
participant W as WS клиенты
YT-->>SRC: liveChatMessages list
SRC->>S: emit new items
S->>W: chat.message
10. Компоненты и развёртывание
flowchart TB
subgraph Desk["Desktop"]
E[Electron main]
R[Renderer Chromium]
E -->|127.0.0.1| N
R -->|HTTP WS| N
end
subgraph Web["Сервер только web"]
I[index.js]
I --> N
end
N[ChatAppServer Node]
subgraph Prov["Провайдеры"]
T[Twitch]
V[VK]
K[Kick]
D[Donations MemeAlerts]
end
N --> Prov
На desktop при занятом порту Electron может подключиться к уже запущенному экземпляру сервера (startOrReuseDesktopServer) — два окна, один процесс Node с бэкендом.
11. События по WebSocket (типы type)
Таблица 11 — Перечень типов сообщений WebSocket
type
Назначение
snapshot
Первичная выдача при подключении: буфер сообщений и актуальное состояние
state
Полный или частичный снимок state: каналы, транспорты twitch/vk, OAuth, revision UI
chat.message
Одно сообщение чата или системное оформленное событие
chat.moderation
Удаление, скрытие, таймаут и др. модерация
chat.annotation
Доп. метки к сообщению
chat.clear-local
Сброс локального отображения
eventBus.append
Центр событий: заголовок и деталь
obs.telemetry
Снимок с OBS WebSocket
now-playing
Трек now playing relay
debug
Отладочное состояние при включённой диагностике
12. Группы HTTP API (фрагмент, актуально для 2.7.10)
Таблица 12 — Группы маршрутов handleHttp / handleApiRequest
Один экземпляр desktop:app.requestSingleInstanceLock в Electron; при втором запуске — сообщение пользователю.
Память и CPU: ограничение буфера сообщений, метрики в state, опциональное давление по памяти.
Безопасность: contextIsolation в Electron, токены на диске в каталоге данных, HTTPS в продакшене по конфигу хоста; HTTP-сервер по умолчанию привязан к 127.0.0.1; чувствительные маршруты (debug, экспорт/импорт настроек, OBS, /api/deck/*) с недоверенных адресов сети требуют заголовок X-CoronerChat-Deck-Token, сверяемый с CORONERCHAT_DECK_TOKEN (см. руководство оператора, §5.14, 8.6).
Zapret: только desktop, отдельный процесс/профили под протоколы DPI.
14. Словарь данных (потоки и поля)
Сообщение чата (в chat.message): id, source, channel, author, text, timestamp, raw (IRC tags / redemption / hype payload), флаги channelPointsRedemption, deleted, pinned и др.
persistedState.uiLocale, dismissedUpdateVersions: язык UI и пропущенные версии апдейта.
persistedState.donationAlertsMinAmount (и связанные поля DA): фильтрация сумм донатов на стороне клиента настроек.
Redemption EventSub: поля id, reward, user_input, плоские user_id / user_login или вложенный user после poller.
Hype Train EventSub: фазы begin / progress / end, в сообщении raw.hypeTrain с level, goal, total.
DonationAlerts / MemeAlerts: события оформляются как сообщения с источником source, отражающим платформу; детали в raw по схеме соответствующего провайдера.
14a. Обновления изделия и локализация UI (сводка)
Канал обновлений (2.7.5). Репозиторий GitHub dorimeryt-alt/CoronerChat зашит в приложение. Проверка при запуске: GET /repos/…/releases/latest (релиз Latest), с отсевом legacy-тегов линии 2.25–2.35. API: POST /api/update/check, /api/update/install (скачивание Setup + NSIS), /api/update/dismiss (skip-версия в dismissedUpdateVersions); «напомнить позже» — только на сессию. Каталог CoronerChat-data при обновлении сохраняется.
Локализация (2.7.5). Языки ru, en, ro, de, fi — словари src/server/i18n/locales, персист uiLocale, POST /api/settings/locale. Клиентский applyI18nDom не затирает узлы с вложенными контролами (фикс смены языка в 2.7.5). См. docs/updates-and-releases.md, docs/i18n.md, docs/security.html.
15. Заключение
Документ описывает архитектуру CoronerChat 2.7.10 (IDEF0, DFD, BPMN, UML); п. 1.5 фиксирует реализованный функционал, включая Rutube, UX-пакет, статистику/достижения, i18n и автообновление. Information item: Software Architecture Description (ISO/IEC/IEEE 42010, 15289). Эксплуатация — docs/coronerchat-operation-print.html, docs/guide.html (ISO/IEC 26514). При изменении кода синхронно обновляйте маршруты, имена модулей и диаграммы.
Версия изделия: 2.7.10 (package.json). Печать: A4. Публикация: GitHub Pages docs/.
