chat/.sw

# Development state snapshot

Project: Raspi Telegram Live Chat
Repository: https://github.com/viktor138irk/chat
Owner: viktor138irk
Default branch: main

This file is a compact project memory for continuing development in a new chat/dialog.

## Product idea

Build a self-hosted live chat system similar to Jivo, but with Telegram as the operator interface.

Website visitors use an embeddable widget. Messages go to selected Telegram operators. Operators reply in Telegram, and replies return to the website widget.

## Main architecture

```text
Website with embedded widget
  -> widget.example.ru static widget.js from VPS/FastPanel
  -> api.example.ru public HTTPS endpoint on VPS/FastPanel
  -> VPS reverse proxy
  -> WireGuard tunnel
  -> Raspberry Pi 3B backend at home
  -> SQLite + Telegram bot
```

## Deployment decisions

- Cloudflare must not be used because of availability issues in Russia.
- Frontend is hosted on VPS with FastPanel.
- FastPanel must manage domains, SSL, and web server configs manually.
- Project scripts must not create domains or edit global FastPanel configs.
- Raspberry Pi stays at home and should not expose public ports.
- VPS is the only public entry point.
- VPS connects to Raspberry Pi through WireGuard.
- api.example.ru is only a reverse proxy, not a static site.
- admin.example.ru serves the admin panel static files.
- widget.example.ru serves the embeddable widget static files.

## Raspberry Pi target

Recommended device:

- Raspberry Pi 3 Model B
- Raspberry Pi OS Lite 32-bit
- Node.js backend
- SQLite
- PM2
- WireGuard client

Do not expose Raspberry Pi directly to the internet.

Backend should listen on port 3000 and be reachable only through WireGuard from VPS.

## VPS/FastPanel target

VPS with FastPanel manually configured by the user.

Recommended subdomains:

```text
admin.example.ru   -> static admin panel
widget.example.ru  -> static widget
api.example.ru     -> reverse proxy to Raspberry Pi backend
```

DNS A-records for all three point to the VPS IP.

FastPanel webroots are expected to look like:

```text
/var/www/<fastpanel-user>/data/www/admin.example.ru
/var/www/<fastpanel-user>/data/www/widget.example.ru
```

api.example.ru may have a webroot created by FastPanel, but project files must not be published there. It should proxy to:

```text
http://10.8.0.2:3000
```

## Ports

Home router / Raspberry Pi:

- No port forwarding required.
- Backend port 3000 should be available only inside WireGuard.
- SSH may be available only in local LAN if needed.

VPS:

- 80/tcp for HTTP/Let's Encrypt
- 443/tcp for HTTPS admin/widget/api
- 51820/udp for WireGuard
- SSH port, usually 22/tcp or custom

## SOCKS5 requirement

Telegram settings must support optional SOCKS5 proxy:

```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 eventually expose:

- enable/disable SOCKS5
- host
- port
- username
- password
- test connection button

## Frontend update decision

The user wants manual-safe frontend installation on VPS first, to avoid breaking FastPanel.

Future update mechanism:

- Assistant can prepare an update bundle file.
- User uploads it to VPS.
- Auto-updater applies changes safely.
- Updates can cover admin, widget, and backend/API instructions.

Recommended project directory on VPS:

```text
/opt/raspi-chat/
  source/
  updates/
  backups/
  logs/
  build/
```

FastPanel owns public directories:

```text
/var/www/<fastpanel-user>/data/www/admin.example.ru
/var/www/<fastpanel-user>/data/www/widget.example.ru
```

## FastPanel safety rules

Never from project scripts:

- edit `/etc/nginx/nginx.conf`
- overwrite FastPanel vhost configs
- run broad `systemctl restart nginx`
- install packages that replace FastPanel web stack
- run frontend as root
- bind frontend services to ports 80/443
- delete parent `/var/www` directories

Static deployment should copy files only into exact domain webroots.

Use rsync carefully:

```bash
rsync -av --delete admin-panel/dist/ /var/www/siteuser/data/www/admin.example.ru/
rsync -av --delete widget/dist/ /var/www/siteuser/data/www/widget.example.ru/
```

Never run `rsync --delete` against `/var/www` or parent folders.

## Current repository structure

```text
.
├── .gitignore
├── .sw
├── README.md
├── package.json
├── backend/
│   ├── .env.example
│   ├── package.json
│   └── src/
│       ├── config.js
│       └── server.js
├── admin-panel/
│   ├── index.html
│   ├── package.json
│   └── src/
│       ├── main.jsx
│       └── styles.css
├── widget/
│   ├── index.html
│   ├── package.json
│   └── src/
│       └── widget.js
├── deploy/
│   └── deploy-agent/
│       ├── .env.example
│       ├── package.json
│       └── src/
│           └── deploy-frontend.js
└── docs/
    ├── FASTPANEL.md
    ├── FASTPANEL_MANUAL_FRONTEND.md
    ├── INSTALL.md
    ├── RASPBERRY_PI.md
    └── UPDATE_BUNDLE.md
```

## Implemented so far

### Root workspace

- npm workspaces configured.
- Root scripts:
  - `dev:backend`
  - `dev:admin`
  - `build:admin`
  - `build:widget`
  - `build`
  - `deploy:frontend`

### Backend

Stack:

- Node.js
- Fastify
- @fastify/cors
- @fastify/rate-limit
- @fastify/websocket
- better-sqlite3 dependency already added but schema not implemented yet
- telegraf dependency already added but Telegram bridge not implemented yet

Current endpoints:

```text
GET  /health
GET  /api/config/public
POST /api/widget/message
GET  /ws
```

`/api/widget/message` currently validates basic fields and returns accepted. Persistence and Telegram forwarding are not implemented yet.

### Admin panel

React/Vite shell exists.

It shows:

- project dashboard
- API health check
- FastPanel-safe deployment note
- SOCKS5 note

### Widget

Vanilla JS widget shell exists.

It:

- creates chat button
- opens chat panel
- creates visitorId in localStorage
- sends messages to backend endpoint

Current embed example:

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

Need to ensure production Vite build emits stable `widget.js` file.

### Deploy agent

FastPanel-safe deploy script exists:

```text
deploy/deploy-agent/src/deploy-frontend.js
```

It:

- git fetch/pull
- npm ci
- builds admin-panel
- builds widget
- validates FastPanel webroot paths
- rsyncs dist files into admin/widget webroots
- does not touch FastPanel configs

Important env variable name fixed:

```env
FASTPANEL_SAFE_MODE=true
```

## Existing docs

- `docs/INSTALL.md`: full install guide for VPS + Raspberry Pi.
- `docs/FASTPANEL.md`: FastPanel-safe deployment guide.
- `docs/FASTPANEL_MANUAL_FRONTEND.md`: manual frontend installation through FastPanel.
- `docs/RASPBERRY_PI.md`: Raspberry Pi setup.
- `docs/UPDATE_BUNDLE.md`: future update bundle workflow.

## Important previous commits

- Initial project spec: `aea8a9f49089ffd6b5a8ace365fc4eaa8c4ea154`
- Frontend deployment requirement: `1a914b9e546f6a0d9b60be6f8cf80858b1d25a75`
- FastPanel-safe requirement: `80f0e77e76f6a0b79e875fed5baf2243fbe0a11e`
- Initial project skeleton: multiple commits after that
- Install guide: `4f86690a0118f69243ce4da9b515aaace5b20017`
- Manual FastPanel frontend guide: `ba08112dc628fd276a2f8eade63145b32aa42c95`
- Update bundle workflow: `b1fa5ead43f33e80c7208b98bcea6e0fa68d5682`

## Next development steps

1. Fix widget production build so it outputs stable `widget.js`.
2. Add SQLite database layer:
   - sites
   - operators
   - site_operators
   - visitors
   - conversations
   - messages
   - settings
3. Persist widget messages.
4. Implement Telegram bot bridge:
   - send website messages to allowed operators
   - map Telegram replies to conversations
   - send replies back to widget via WebSocket
5. Add admin auth.
6. Add admin CRUD:
   - sites
   - operators
   - operator-site permissions
   - Telegram settings
   - SOCKS5 settings
7. Add origin/domain validation:
   - `site_id + Origin` must match configured site.
8. Add manual update section in admin panel.
9. Add update bundle generator and apply script.
10. Prepare Android-ready API later.

## User preferences and constraints

- User wants practical development, not only planning.
- User wants all work in GitHub repository `viktor138irk/chat`.
- User wants to be able to resume development in a new dialog using this `.sw` file.
- User prefers not to risk breaking FastPanel.
- User wants manual control over domains in FastPanel.
- User wants future auto-update file/bundle workflow.
- User confirmed: `api.example.ru` or `pi.example.ru` is just proxied.

## How to continue in a new chat

Open this file first. Then continue from "Next development steps".

Recommended next task:

```text
Implement SQLite schema and message persistence in backend.
```