diff --git a/README.md b/README.md index d17329a..8b9e9d4 100644 --- a/README.md +++ b/README.md @@ -1,317 +1,138 @@ -# Raspi Telegram Live Chat +# WSChat -Self-hosted live chat system for Raspberry Pi with embeddable website widget, web admin panel, Telegram as the operator interface, and a separate VPS-hosted frontend. +Self-hosted онлайн-консультант для сайта (аналог Jivo/Tidio) с Telegram в роли интерфейса оператора. Посетитель пишет через встраиваемый виджет, сообщение попадает в бэкенд, оттуда рассылается назначенным операторам в Telegram; ответ оператора возвращается в виджет по WebSocket. Предназначен для владельца одного или нескольких сайтов, который не хочет платить за SaaS-чат и держит инфраструктуру на своём VPS с FastPanel. -## Goal +## Стек -Build a lightweight Jivo-like chat platform where visitors write through a website widget and only Telegram operators configured in the admin panel receive and answer messages. +- Node.js 20+, ESM. +- Backend: Fastify 5, `@fastify/cors`, `@fastify/rate-limit`, `@fastify/websocket`. +- БД: SQLite через `better-sqlite3` (WAL, foreign keys), схема создаётся кодом при старте. +- Telegram: `telegraf` 4, опционально через SOCKS5 (`socks-proxy-agent`, схема `socks5h://`). +- Админ-панель: React + Vite, `lucide-react`. +- Виджет: ванильный JS, сборка Vite, изоляция через Shadow DOM. +- Деплой: npm workspaces, PM2, FastPanel (nginx/Apache под управлением панели), rsync. -## Target deployment +## Структура -Primary target for MVP: +| Путь | Назначение | +|---|---| +| `package.json` | Корневой workspace: `backend`, `admin-panel`, `widget`, `deploy/deploy-agent`; скрипты сборки и деплоя | +| `backend/src/server.js` | Fastify-приложение: HTTP API, CORS по списку сайтов, rate limit, WebSocket `/ws`, старт Telegram-моста | +| `backend/src/db.js` | Подключение к SQLite, миграция схемы (`sites`, `operators`, `site_operators`, `visitors`, `conversations`, `messages`, `settings`), запросы и работа с настройками | +| `backend/src/telegram.js` | Telegraf-мост: рассылка сообщений операторам, разбор ответов (reply и inline-кнопка выбора диалога), команда `/status`, перезапуск бота на лету | +| `backend/src/config.js` | Чтение `.env`, значения по умолчанию, production-путь к базе | +| `backend/.env.example` | Шаблон переменных окружения бэкенда | +| `admin-panel/src/main.jsx` | Панель: статистика, список сайтов и операторов, embed-код, настройки Telegram/SOCKS5, лента последних сообщений, диагностика `/health` | +| `admin-panel/vite.config.js` | Сборка с `base: '/admin/'` | +| `widget/src/widget.js` | Встраиваемый виджет: Shadow DOM, localStorage-идентификатор посетителя, POST сообщения и WebSocket-подписка на ответы | +| `widget/vite.config.js` | Сборка с фиксированным именем артефакта `widget.js` | +| `deploy/vps/install.sh` | Установщик VPS: пакеты, Node.js, PM2, `npm install`, сборка фронтенда, запуск бэкенда | +| `deploy/vps/bootstrap.sh`, `deploy/raspberry/bootstrap.sh` | Первичная подготовка VPS и Raspberry Pi | +| `deploy/deploy-agent/src/deploy-frontend.js` | Агент обновления фронтенда: `git pull`, `npm ci`, сборка, rsync в webroot FastPanel с проверкой безопасности пути | +| `docs/` | Инструкции: `INSTALL.md`, `VPS_ONLY_INSTALL.md`, `FASTPANEL.md`, `FASTPANEL_MANUAL_FRONTEND.md`, `RASPBERRY_PI.md`, `UPDATE_BUNDLE.md` | +| `.sw` | Журнал разработки: текущее состояние, продовые пути, диагностика, список нерешённых задач | +| `README.upstream.md` | Исходное техническое задание проекта (сохранено при пересборке README) | -- Raspberry Pi 3 Model B at home -- Raspberry Pi OS Lite 32-bit -- Backend API on Raspberry Pi -- Telegram bot on Raspberry Pi -- SQLite database on Raspberry Pi -- VPS with FastPanel for admin panel, widget.js, static assets, HTTPS, and public reverse proxy -- WireGuard between VPS and Raspberry Pi -- Domain/site management through FastPanel where possible +## Как запустить -Cloudflare must not be required for this project. - -Recommended OS for Raspberry Pi 3B MVP: - -- Raspberry Pi OS Lite 32-bit for maximum RAM economy and stability on 1 GB RAM -- Raspberry Pi OS Lite 64-bit can be tested later if specific ARM64 packages are needed - -## Core components - -```text -website widget -> VPS FastPanel/Nginx/API proxy -> WireGuard -> Raspberry Pi backend -> SQLite -> Telegram bot -> operators - -VPS also serves: -- admin panel -- widget.js -- static assets -``` - -## MVP modules - -- Backend API -- WebSocket gateway -- Telegram bot bridge -- Embeddable website widget -- Web admin panel -- SQLite storage -- Operator/site access rules -- SOCKS5 proxy settings for Telegram connectivity -- Frontend deployment management from admin panel -- FastPanel-safe frontend publishing on VPS - -## Required admin settings - -### Telegram bot - -- Bot token -- Webhook or polling mode -- Allowed operators -- Operator-to-site mapping - -### SOCKS5 proxy - -The system must support optional SOCKS5 configuration for Telegram requests: - -```env -TELEGRAM_PROXY_ENABLED=false -TELEGRAM_PROXY_TYPE=socks5 -TELEGRAM_PROXY_HOST=127.0.0.1 -TELEGRAM_PROXY_PORT=9050 -TELEGRAM_PROXY_USERNAME= -TELEGRAM_PROXY_PASSWORD= -``` - -Admin panel should expose: - -- Enable/disable SOCKS5 -- Proxy host -- Proxy port -- Username -- Password -- Test connection button - -Sensitive fields must be stored encrypted or kept in environment variables for MVP. - -### FastPanel-safe frontend hosting - -The frontend server uses FastPanel. The project deployment must not break, overwrite, restart, or bypass FastPanel-managed services. - -Hard rules: - -- Do not edit global FastPanel configs directly -- Do not overwrite `/etc/nginx/nginx.conf` -- Do not overwrite FastPanel-generated virtual host configs -- Do not run broad `systemctl restart nginx` from the deploy script -- Do not install packages that replace FastPanel web stack components -- Do not run frontend as root -- Do not bind frontend services to ports `80` or `443` -- Prefer static build publishing into a FastPanel-created site directory -- Use `nginx -t` before any reload if reload is unavoidable -- Prefer no reload at all for static frontend updates - -Recommended FastPanel model: - -```text -FastPanel creates domains/sites: -- admin.example.ru -- widget.example.ru -- api.example.ru - -Deploy script only updates files inside the allowed web root: -- admin panel build files -- widget.js -- widget assets -``` - -Recommended FastPanel-safe paths: - -```text -/var/www//data/www/admin.example.ru -/var/www//data/www/widget.example.ru -/opt/raspi-chat/source -/opt/raspi-chat/releases/ -/opt/raspi-chat/current -> /opt/raspi-chat/releases/ -``` - -Deployment should copy or rsync built static files into the FastPanel site directories: - -```text -admin-panel/dist/* -> /var/www//data/www/admin.example.ru/ -widget/dist/* -> /var/www//data/www/widget.example.ru/ -``` - -The API reverse proxy for `api.example.ru` should be configured through FastPanel custom Nginx directives if available, or through a separate include file that FastPanel will not overwrite. - -FastPanel compatibility must be treated as a deployment requirement, not an afterthought. - -### Frontend deployment updates - -The admin panel must include a deployment section for updating the VPS-hosted frontend. - -Required modes: - -1. Manual update by button -2. Automatic update by webhook from GitHub -3. Optional scheduled update check - -Admin panel should expose: - -- Current frontend version -- Current commit hash -- Last deployment time -- Last deployment status -- Update branch, default: `main` -- Button: `Check for updates` -- Button: `Update frontend now` -- Deployment logs -- Rollback to previous frontend build -- Lock to prevent parallel deployments -- FastPanel compatibility status -- Target FastPanel web root paths - -Frontend deployment flow: - -```text -Admin clicks update button - -> backend validates admin permissions - -> backend calls deploy agent on VPS - -> VPS pulls latest repository changes - -> VPS builds admin-panel and widget - -> VPS verifies FastPanel-safe target paths - -> VPS publishes new static build atomically - -> backend stores deployment result - -> admin panel shows status and logs -``` - -Recommended deploy command on VPS: +Локально: ```bash -git fetch origin main -npm ci -npm run build --workspace admin-panel -npm run build --workspace widget +npm install +cp backend/.env.example backend/.env # заполнить значения +npm run dev:backend # node --watch backend/src/server.js +npm run dev:admin # Vite, админка +npm --workspace widget run dev # Vite, виджет на порту 5174 ``` -Publishing must be atomic and FastPanel-safe: +Сборка фронтенда: -```text -build new release directory -verify build artifacts -verify target directories are inside allowed FastPanel web roots -copy files with rsync --delete only inside those roots -never delete parent web root directories -never touch FastPanel system configs +```bash +npm run build # build:admin + build:widget ``` -Admin deployment permissions: +Отдельных миграций нет: схема SQLite создаётся функцией `migrate()` при старте бэкенда, база и каталог создаются автоматически по `DATABASE_PATH`. -- Only users with role `admin` can trigger frontend updates -- Deployment endpoint must require JWT auth -- Deployment webhook must require secret token validation -- All deployment attempts must be logged +Установка на VPS (скрипт ставит пакеты, Node.js, PM2, собирает фронтенд и поднимает бэкенд под PM2): -Environment variables: - -```env -FRONTEND_DEPLOY_ENABLED=true -FRONTEND_DEPLOY_MODE=local-vps -FRONTEND_DEPLOY_BRANCH=main -FRONTEND_DEPLOY_SOURCE_PATH=/opt/raspi-chat/source -FRONTEND_DEPLOY_RELEASES_PATH=/opt/raspi-chat/releases -FRONTEND_DEPLOY_ADMIN_WEBROOT=/var/www/example_user/data/www/admin.example.ru -FRONTEND_DEPLOY_WIDGET_WEBROOT=/var/www/example_user/data/www/widget.example.ru -FRONTEND_DEPLOY_WEBHOOK_SECRET= -FASTPANEL_SAFE_MODE=true +```bash +cp deploy/vps/.env.example deploy/vps/.env +sudo bash deploy/vps/install.sh ``` -MVP implementation should run the deployment agent directly on the VPS. The deploy agent must have permissions only for the project source, release directory, and specific FastPanel web roots. +Публикация фронтенда в webroot FastPanel: -## Website widget +```bash +npm run deploy:frontend # deploy/deploy-agent, требует свой .env +``` -Example embed code: +Проверка: + +```bash +curl -s http://127.0.0.1:3000/health +pm2 logs wschat-backend --lines 100 +``` + +Встраивание виджета на сайт: ```html - + ``` -The widget must connect to the public API endpoint on VPS: +## Конфигурация -```text -https://api.example.ru -wss://api.example.ru/ws -``` +### `backend/.env` -## Message flow +| Переменная | Назначение | Пример | +|---|---|---| +| `APP_ENV` | Режим работы; в `production` меняется путь к базе по умолчанию и отключается pino-pretty | `production` | +| `APP_HOST` | Адрес прослушивания бэкенда | `127.0.0.1` | +| `APP_PORT` | Порт бэкенда | `3000` | +| `PUBLIC_API_URL` | Публичный URL API, отдаётся виджету через `/api/config/public` | `https://api.example.ru` | +| `PUBLIC_WS_URL` | Публичный WebSocket URL | `wss://api.example.ru/ws` | +| `TRUST_PROXY` | Доверять заголовкам reverse proxy | `true` | +| `DATABASE_PATH` | Путь к файлу SQLite | `/opt/ws-chat/data/chat.sqlite` | +| `ADMIN_ORIGIN` | Origin админки для CORS | `https://admin.example.ru` | +| `WIDGET_ORIGIN` | Origin виджета для CORS и домен сайта по умолчанию | `https://widget.example.ru` | +| `TELEGRAM_BOT_TOKEN` | Токен бота; при первом старте копируется в таблицу `settings`, дальше редактируется из админки | см. `.env` | +| `TELEGRAM_PROXY_ENABLED` | Включить SOCKS5 для Telegram | `false` | +| `TELEGRAM_PROXY_TYPE` | Тип прокси; в коде поддерживается только `socks5` | `socks5` | +| `TELEGRAM_PROXY_HOST` / `TELEGRAM_PROXY_PORT` | Адрес и порт прокси | `127.0.0.1` / `9050` | +| `TELEGRAM_PROXY_USERNAME` / `TELEGRAM_PROXY_PASSWORD` | Учётные данные прокси | см. `.env` | +| `JWT_SECRET` | Объявлен в конфиге, но нигде не используется — авторизации нет | см. `.env` | +| `FRONTEND_DEPLOY_ENABLED`, `FRONTEND_DEPLOY_MODE`, `FASTPANEL_SAFE_MODE` | Объявлены в `.env.example`, бэкендом не читаются | `false` | -```text -Visitor sends message on website - -> widget sends message to VPS api.example.ru - -> VPS proxies request through WireGuard to Raspberry Pi backend - -> backend validates site_id and origin domain - -> backend stores message - -> backend finds active operators assigned to this site - -> Telegram bot sends message only to those operators - -> operator replies in Telegram - -> backend maps reply to conversation - -> message is delivered back to website widget through WebSocket -``` +Приоритет источников: значения Telegram/SOCKS5 после первого запуска хранятся в таблице `settings` SQLite и правятся через админку; `.env` задаёт только начальные значения. -## Future Android app +### `deploy/vps/.env` -The backend must expose stable REST and WebSocket APIs so an Android app can later work as another operator interface. +`PROJECT_ROOT`, `SOURCE_PATH`, `DATA_PATH`, `LOGS_PATH`, `BACKUPS_PATH`, `UPDATES_PATH`, `ADMIN_WEBROOT`, `WIDGET_WEBROOT`, `BACKEND_HOST`, `BACKEND_PORT`, `PUBLIC_API_URL`, `PUBLIC_WS_URL`, `FASTPANEL_SAFE_MODE`, `PM2_PROCESS_NAME`, `NODE_MAJOR`. -Planned Android-ready API concepts: +### `deploy/deploy-agent/.env` -- JWT auth -- refresh tokens -- operator sessions -- conversation list -- message history -- push-ready notification events -- WebSocket live updates +`FRONTEND_DEPLOY_BRANCH`, `FRONTEND_DEPLOY_SOURCE_PATH`, `FRONTEND_DEPLOY_ADMIN_WEBROOT`, `FRONTEND_DEPLOY_WIDGET_WEBROOT`, `FASTPANEL_SAFE_MODE`. При `FASTPANEL_SAFE_MODE != false` webroot обязан лежать внутри `/var/www//data/www/`, иначе деплой прерывается. -## Initial stack +## Состояние -- Node.js -- Fastify -- WebSocket -- SQLite -- React + Vite admin panel -- Vanilla JS widget -- Telegram Bot API -- WireGuard -- FastPanel-managed web server on VPS -- PM2 preferred for Raspberry Pi 3B MVP +Рабочий MVP, разработка остановлена. 106 коммитов, все от 2026-05-08, последний коммит — 2026-05-08. По записям `.sw` система была развёрнута и работала: виджет и админка на `widget.stackworks.ru`, API на `api.stackworks.ru`, бэкенд под PM2, SQLite в `/opt/ws-chat/data/chat.sqlite`. -## Development phases +Сквозной сценарий реализован полностью: виджет → API → Telegram-оператор → ответ → WebSocket → виджет. Управление сайтами, операторами и настройками Telegram/SOCKS5 работает из админки. -### Phase 1 +Raspberry Pi (изначальная цель проекта, см. `README.upstream.md` и `docs/RASPBERRY_PI.md`) из MVP исключён — в `.sw` указана причина: нестабильность Node.js/ОС на Pi. -- Website widget -- Backend API -- Telegram message forwarding -- Reply from Telegram back to website -- SQLite persistence +## Что не доделано -### Phase 2 +Явных `TODO`/`FIXME` в коде нет; список ниже собран из кода и раздела «Current next steps» в `.sw`. -- Admin login -- Site management -- Operator management -- Site/operator permissions -- Widget embed code generator -- SOCKS5 proxy settings - -### Phase 3 - -- FastPanel-safe VPS frontend deployment scripts -- Admin button for frontend update -- Deployment logs -- GitHub webhook auto-update -- Frontend rollback support - -### Phase 4 - -- Conversation history -- Dialog statuses -- Rate limiting -- Origin/domain validation -- Backup script -- Deployment guide for Raspberry Pi, VPS, FastPanel, and WireGuard - -### Phase 5 - -- Android app API preparation -- Push notification model -- Multi-device operator sessions +- Нет авторизации в админ-панели. Все эндпоинты `/api/admin/*` открыты без проверки; `JWT_SECRET` объявлен, но не используется. Это главный незакрытый риск, зафиксированный и в самом `.sw`. +- Нет страницы диалогов в админке: есть только лента последних сообщений, нельзя открыть переписку целиком. +- Не реализованы статусы диалогов (`open`/`closed`) и назначение оператора «взять в работу» — поля `status` и `assigned_operator_id` в БД есть, UI и API для них нет. +- Нет удаления/редактирования сайтов и операторов: реализованы только `GET`/`POST` сайтов и привязка/отвязка операторов. +- Не реализована обещанная в ТЗ система деплоя из админки: нет ни кнопки обновления, ни GitHub-вебхука, ни откатов, ни логов деплоя. Есть только CLI-агент `deploy-frontend.js`. +- `test-proxy` не проверяет соединение — функция `validateSocks5Settings` только валидирует поля формы. +- Нет офлайн-режима (сбор имени/телефона/email посетителя), звуковых уведомлений и счётчиков непрочитанного. +- Нет кастомизации виджета из админки (заголовок, цвет, позиция) — параметры зашиты в `widget.js`. +- Нет тестов и CI: тестовых файлов, конфигов линтера и workflow в репозитории нет. +- Планы, отмеченные в `.sw` как отложенные: перенос админки на отдельный поддомен, переход с SQLite на PostgreSQL, Docker Compose/установщик, JWT и API под будущее Android-приложение. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..d17329a --- /dev/null +++ b/README.upstream.md @@ -0,0 +1,317 @@ +# Raspi Telegram Live Chat + +Self-hosted live chat system for Raspberry Pi with embeddable website widget, web admin panel, Telegram as the operator interface, and a separate VPS-hosted frontend. + +## Goal + +Build a lightweight Jivo-like chat platform where visitors write through a website widget and only Telegram operators configured in the admin panel receive and answer messages. + +## Target deployment + +Primary target for MVP: + +- Raspberry Pi 3 Model B at home +- Raspberry Pi OS Lite 32-bit +- Backend API on Raspberry Pi +- Telegram bot on Raspberry Pi +- SQLite database on Raspberry Pi +- VPS with FastPanel for admin panel, widget.js, static assets, HTTPS, and public reverse proxy +- WireGuard between VPS and Raspberry Pi +- Domain/site management through FastPanel where possible + +Cloudflare must not be required for this project. + +Recommended OS for Raspberry Pi 3B MVP: + +- Raspberry Pi OS Lite 32-bit for maximum RAM economy and stability on 1 GB RAM +- Raspberry Pi OS Lite 64-bit can be tested later if specific ARM64 packages are needed + +## Core components + +```text +website widget -> VPS FastPanel/Nginx/API proxy -> WireGuard -> Raspberry Pi backend -> SQLite -> Telegram bot -> operators + +VPS also serves: +- admin panel +- widget.js +- static assets +``` + +## MVP modules + +- Backend API +- WebSocket gateway +- Telegram bot bridge +- Embeddable website widget +- Web admin panel +- SQLite storage +- Operator/site access rules +- SOCKS5 proxy settings for Telegram connectivity +- Frontend deployment management from admin panel +- FastPanel-safe frontend publishing on VPS + +## Required admin settings + +### Telegram bot + +- Bot token +- Webhook or polling mode +- Allowed operators +- Operator-to-site mapping + +### SOCKS5 proxy + +The system must support optional SOCKS5 configuration for Telegram requests: + +```env +TELEGRAM_PROXY_ENABLED=false +TELEGRAM_PROXY_TYPE=socks5 +TELEGRAM_PROXY_HOST=127.0.0.1 +TELEGRAM_PROXY_PORT=9050 +TELEGRAM_PROXY_USERNAME= +TELEGRAM_PROXY_PASSWORD= +``` + +Admin panel should expose: + +- Enable/disable SOCKS5 +- Proxy host +- Proxy port +- Username +- Password +- Test connection button + +Sensitive fields must be stored encrypted or kept in environment variables for MVP. + +### FastPanel-safe frontend hosting + +The frontend server uses FastPanel. The project deployment must not break, overwrite, restart, or bypass FastPanel-managed services. + +Hard rules: + +- Do not edit global FastPanel configs directly +- Do not overwrite `/etc/nginx/nginx.conf` +- Do not overwrite FastPanel-generated virtual host configs +- Do not run broad `systemctl restart nginx` from the deploy script +- Do not install packages that replace FastPanel web stack components +- Do not run frontend as root +- Do not bind frontend services to ports `80` or `443` +- Prefer static build publishing into a FastPanel-created site directory +- Use `nginx -t` before any reload if reload is unavoidable +- Prefer no reload at all for static frontend updates + +Recommended FastPanel model: + +```text +FastPanel creates domains/sites: +- admin.example.ru +- widget.example.ru +- api.example.ru + +Deploy script only updates files inside the allowed web root: +- admin panel build files +- widget.js +- widget assets +``` + +Recommended FastPanel-safe paths: + +```text +/var/www//data/www/admin.example.ru +/var/www//data/www/widget.example.ru +/opt/raspi-chat/source +/opt/raspi-chat/releases/ +/opt/raspi-chat/current -> /opt/raspi-chat/releases/ +``` + +Deployment should copy or rsync built static files into the FastPanel site directories: + +```text +admin-panel/dist/* -> /var/www//data/www/admin.example.ru/ +widget/dist/* -> /var/www//data/www/widget.example.ru/ +``` + +The API reverse proxy for `api.example.ru` should be configured through FastPanel custom Nginx directives if available, or through a separate include file that FastPanel will not overwrite. + +FastPanel compatibility must be treated as a deployment requirement, not an afterthought. + +### Frontend deployment updates + +The admin panel must include a deployment section for updating the VPS-hosted frontend. + +Required modes: + +1. Manual update by button +2. Automatic update by webhook from GitHub +3. Optional scheduled update check + +Admin panel should expose: + +- Current frontend version +- Current commit hash +- Last deployment time +- Last deployment status +- Update branch, default: `main` +- Button: `Check for updates` +- Button: `Update frontend now` +- Deployment logs +- Rollback to previous frontend build +- Lock to prevent parallel deployments +- FastPanel compatibility status +- Target FastPanel web root paths + +Frontend deployment flow: + +```text +Admin clicks update button + -> backend validates admin permissions + -> backend calls deploy agent on VPS + -> VPS pulls latest repository changes + -> VPS builds admin-panel and widget + -> VPS verifies FastPanel-safe target paths + -> VPS publishes new static build atomically + -> backend stores deployment result + -> admin panel shows status and logs +``` + +Recommended deploy command on VPS: + +```bash +git fetch origin main +npm ci +npm run build --workspace admin-panel +npm run build --workspace widget +``` + +Publishing must be atomic and FastPanel-safe: + +```text +build new release directory +verify build artifacts +verify target directories are inside allowed FastPanel web roots +copy files with rsync --delete only inside those roots +never delete parent web root directories +never touch FastPanel system configs +``` + +Admin deployment permissions: + +- Only users with role `admin` can trigger frontend updates +- Deployment endpoint must require JWT auth +- Deployment webhook must require secret token validation +- All deployment attempts must be logged + +Environment variables: + +```env +FRONTEND_DEPLOY_ENABLED=true +FRONTEND_DEPLOY_MODE=local-vps +FRONTEND_DEPLOY_BRANCH=main +FRONTEND_DEPLOY_SOURCE_PATH=/opt/raspi-chat/source +FRONTEND_DEPLOY_RELEASES_PATH=/opt/raspi-chat/releases +FRONTEND_DEPLOY_ADMIN_WEBROOT=/var/www/example_user/data/www/admin.example.ru +FRONTEND_DEPLOY_WIDGET_WEBROOT=/var/www/example_user/data/www/widget.example.ru +FRONTEND_DEPLOY_WEBHOOK_SECRET= +FASTPANEL_SAFE_MODE=true +``` + +MVP implementation should run the deployment agent directly on the VPS. The deploy agent must have permissions only for the project source, release directory, and specific FastPanel web roots. + +## Website widget + +Example embed code: + +```html + +``` + +The widget must connect to the public API endpoint on VPS: + +```text +https://api.example.ru +wss://api.example.ru/ws +``` + +## Message flow + +```text +Visitor sends message on website + -> widget sends message to VPS api.example.ru + -> VPS proxies request through WireGuard to Raspberry Pi backend + -> backend validates site_id and origin domain + -> backend stores message + -> backend finds active operators assigned to this site + -> Telegram bot sends message only to those operators + -> operator replies in Telegram + -> backend maps reply to conversation + -> message is delivered back to website widget through WebSocket +``` + +## Future Android app + +The backend must expose stable REST and WebSocket APIs so an Android app can later work as another operator interface. + +Planned Android-ready API concepts: + +- JWT auth +- refresh tokens +- operator sessions +- conversation list +- message history +- push-ready notification events +- WebSocket live updates + +## Initial stack + +- Node.js +- Fastify +- WebSocket +- SQLite +- React + Vite admin panel +- Vanilla JS widget +- Telegram Bot API +- WireGuard +- FastPanel-managed web server on VPS +- PM2 preferred for Raspberry Pi 3B MVP + +## Development phases + +### Phase 1 + +- Website widget +- Backend API +- Telegram message forwarding +- Reply from Telegram back to website +- SQLite persistence + +### Phase 2 + +- Admin login +- Site management +- Operator management +- Site/operator permissions +- Widget embed code generator +- SOCKS5 proxy settings + +### Phase 3 + +- FastPanel-safe VPS frontend deployment scripts +- Admin button for frontend update +- Deployment logs +- GitHub webhook auto-update +- Frontend rollback support + +### Phase 4 + +- Conversation history +- Dialog statuses +- Rate limiting +- Origin/domain validation +- Backup script +- Deployment guide for Raspberry Pi, VPS, FastPanel, and WireGuard + +### Phase 5 + +- Android app API preparation +- Push notification model +- Multi-device operator sessions