chat/README.upstream.md

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

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:

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:

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:

/var/www/<fastpanel-user>/data/www/admin.example.ru
/var/www/<fastpanel-user>/data/www/widget.example.ru
/opt/raspi-chat/source
/opt/raspi-chat/releases/<timestamp>
/opt/raspi-chat/current -> /opt/raspi-chat/releases/<timestamp>

Deployment should copy or rsync built static files into the FastPanel site directories:

admin-panel/dist/* -> /var/www/<fastpanel-user>/data/www/admin.example.ru/
widget/dist/*      -> /var/www/<fastpanel-user>/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:

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:

git fetch origin main
npm ci
npm run build --workspace admin-panel
npm run build --workspace widget

Publishing must be atomic and FastPanel-safe:

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:

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:

<script src="https://widget.example.ru/widget.js" data-site-id="site_xxxxx"></script>

The widget must connect to the public API endpoint on VPS:

https://api.example.ru
wss://api.example.ru/ws

Message flow

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