SWChat/README.upstream.md

Pulse / SWChat

Pulse — self-hosted Android/Web мессенджер на базе Matrix для экосистемы StackWorks.

Техническое имя репозитория пока остаётся SWChat. Пользовательский бренд продукта — Pulse by StackWorks.

Проект строится как собственная платформа связи:

• Matrix Core на отдельном сервере;
• PostgreSQL;
• FastPanel reverse proxy как публичный HTTPS слой;
• официальный Matrix/Element-клиент для первого тестирования;
• будущий web-клиент;
• будущий Android-клиент;
• будущая админ-панель;
• безопасная архитектура без вмешательства в существующий production.

Текущая стратегия

Сначала поднимаем и проверяем серверное ядро через официальные Matrix-клиенты.

Порядок:

1. Поднять Pulse/SWChat Core на отдельном сервере.
2. Проверить Matrix/Synapse локально.
3. Настроить публичный домен matrix.stackworks.ru через FastPanel reverse proxy.
4. Проверить работу через официальные клиенты Matrix/Element.
5. Только после стабильной проверки продолжать глубокий ребрендинг собственного Android/Web-клиента.

Это нужно, чтобы не путать проблемы сервера с проблемами будущего собственного UI.

Архитектура

Pulse/SWChat работает по split-server архитектуре.

Новый сервер: Core

На новом сервере размещаются:

• Matrix Synapse;
• PostgreSQL;
• media storage;
• будущий TURN/STUN;
• будущий backend API;
• backups;
• diagnostics.

Текущие private IP:

FastPanel proxy: 192.168.0.221
Matrix/Core:     192.168.0.141

Рекомендуемые домены:

matrix.stackworks.ru      -> Matrix API / Synapse через FastPanel reverse proxy
turn.stackworks.ru        -> новый Core сервер, позже
api-chat.stackworks.ru    -> будущий backend API
admin-chat.stackworks.ru  -> будущая Pulse Admin Panel
chat.stackworks.ru        -> будущий web-клиент

Старый сервер с FastPanel

Старый сервер с FastPanel используется как публичный HTTPS/reverse proxy слой и для будущего frontend/web-клиента.

На нём остаются отдельно:

• ArtistFlow;
• widget.stackworks.ru;
• текущие сайты StackWorks/FastPanel.

Installer не меняет FastPanel, не меняет vhost, не меняет SSL и не трогает существующие сайты.

Что нельзя трогать

Защищённые production-активы:

• artistflow.ru;
• widget.stackworks.ru;
• текущие сайты FastPanel;
• настройки FastPanel без отдельной явной команды.

widget.stackworks.ru на текущем этапе никак не связан с Matrix/Pulse. Новый виджет Pulse не планируется.

Установка Core

На новом сервере Ubuntu:

sudo mkdir -p /opt/swchat
sudo git clone https://github.com/viktor138irk/SWChat.git /opt/swchat/source
cd /opt/swchat/source
sudo SERVER_NAME=matrix.stackworks.ru bash scripts/install.sh

Installer:

• создаёт структуру /opt/swchat;
• устанавливает Docker, если он отсутствует;
• создаёт .env;
• генерирует Synapse config;
• настраивает PostgreSQL для Synapse;
• запускает контейнеры;
• не трогает FastPanel.

Настройка private reverse proxy

По умолчанию Matrix endpoint слушает только localhost:

MATRIX_BIND_HOST=127.0.0.1

Для схемы FastPanel reverse proxy → Core нужно на Core-сервере в /opt/swchat/.env указать private IP Core:

MATRIX_BIND_HOST=192.168.0.141

Затем перезапустить stack:

cd /opt/swchat/source
sudo docker compose --env-file /opt/swchat/.env up -d

И закрыть прямой публичный доступ к Matrix, разрешив порт 8008 только FastPanel proxy:

sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash /opt/swchat/source/scripts/firewall_private_proxy.sh

Проверка с FastPanel proxy:

curl http://192.168.0.141:8008/_matrix/client/versions

Проверка публичного HTTPS endpoint:

curl https://matrix.stackworks.ru/_matrix/client/versions

Проверка после установки

sudo bash /opt/swchat/source/scripts/healthcheck.sh
curl http://127.0.0.1:8008/_matrix/client/versions

Ожидаемый результат curl — JSON с версиями Matrix API.

Тестирование официальными клиентами

До разработки собственного клиента проверяем сервер через:

• Element Web;
• Element Desktop;
• Element Android;
• любые совместимые Matrix-клиенты.

Проверяем:

• регистрацию/логин;
• личные сообщения;
• комнаты;
• отправку файлов;
• стабильность Synapse;
• работу публичного домена.

Android-клиент

Клиентский репозиторий:

https://github.com/viktor138irk/SWChat-App

Важное правило staged-ребрендинга:

• пользовательские тексты и UI можно переводить на Pulse;
• pubspec.yaml name пока должен оставаться fluffychat, пока импорты используют package:fluffychat/...;
• Android applicationId сейчас принят как ru.stackworks.swchat;
• массовая миграция Dart package/imports — отдельный этап.

Структура проекта

.sw                              главный журнал проекта
docker-compose.yml               Matrix/PostgreSQL stack
scripts/install.sh               автоустановщик Core-сервера
scripts/healthcheck.sh           диагностика
scripts/firewall_private_proxy.sh безопасное ограничение 8008 под FastPanel proxy
docs/                            документация
VERSION                          версия проекта

Правило .sw

Файл .sw — главный журнал проекта.

В него обязательно записываются:

• архитектурные решения;
• изменения версий;
• текущий статус;
• следующий шаг;
• ошибки и исправления;
• запреты и защищённые production-активы.

Новый диалог по проекту начинается с чтения .sw.

Текущий статус

Версия: 0.1.2

Core работает на отдельном сервере, публичный HTTPS endpoint https://matrix.stackworks.ru/_matrix/client/versions уже был проверен через FastPanel reverse proxy. Текущий этап — закрепление private proxy/firewall схемы и staged-ребрендинг Android-клиента в Pulse без поломки FluffyChat imports.