# Архитектура

## Общ преглед на потока

По подразбиране (локален tmux + тунел):

```
Browser (phone)
  |
  | HTTPS
  v
Cloudflare Quick Tunnel
  |
  | HTTP/WS
  v
Local Termbridge server
  |
  | PTY
  v
Tmux session
```

Директен режим на sandbox (Daytona, без тунел):

```
Browser (phone)
  |
  | HTTPS
  v
Daytona preview link
  |
  | HTTP/WS
  v
Termbridge server (sandbox)
  |
  | PTY
  v
Tmux session (sandbox)
```

Когато е зададен `--no-tunnel`, Termbridge пропуска Cloudflare и използва предоставения от вас публичен URL.

## Компоненти

### Процес CLI

- Стартира сървъра HTTP, който предоставя активите на UI.
- Стартира WebSocket сървъра за входно-изходните операции на терминала.
- Създава една или повече сесии tmux (или Daytona PTY).
- Издава еднократни токени за достъп.
- Стартира и следи тунела, когато е активиран (Cloudflare към момента).
- В директен режим на sandbox стартира Termbridge вътре в sandbox и изчаква споделения URL.

### Терминален бекенд

- **Бекенд tmux**: Използва `node-pty` за свързване към tmux и обработка на реалните натискания на клавиши и изхода.
- **Бекенд Daytona**: Използва PTY Daytona вътре в sandbox.
- Задава `TERM=xterm-256color` и `COLORTERM=truecolor` за пълна поддръжка на цветовете.
- За tmux изключва лентата на състоянието tmux, за да остави UI изчистен.

### Регистър на терминалите

- Следи наличните терминални сесии.
- Предоставя списък на UI и проверява избраните идентификатори на терминали.

### Удостоверяване и сесия

- Еднократният токен се отпечатва като URL и се кодира в код QR.
- `GET /__tb/s/:token` използва токена и задава сесийна бисквитка.
- WebSocket връзките изискват валидна сесийна бисквитка и CSRF токен.
- CSRF токенът се извлича чрез `GET /__tb/api/csrf` и се предава като параметър на заявката WebSocket.

### Режим на прокси

Когато се подаде `--proxy <port>`:
- Всички маршрути на termbridge са с префикс `/__tb/`
- Заявките, които не са `/__tb/`, се препращат към целевото приложение
- UI показва изгледите Terminal/Preview чрез превключвателя Views
- Изгледът Preview зарежда iframe, насочен към `/`
- WebSocket връзките за HMR се препращат към целевото приложение

### Сигурност

- **CSRF защита**: WebSocket надстройките изискват CSRF токен, за да се предотврати отвличане от друг сайт.
- **Ограничения на входа**: тяло на HTTP от 64KB, WebSocket съобщение от 1MB, входни данни за терминала до 64KB на съобщение.
- **Ограничаване на честотата**: ограничения за всяко IP при използване на токени и WebSocket връзки.

## Крайни точки API

Всички маршрути са с префикс `/__tb/`, за да се избегнат конфликти с проксираните приложения:

- `GET /__tb/healthz` - проверка на изправността
- `GET /__tb/s/:token` - използване на токен → бисквитка → пренасочване
- `GET /__tb/api/terminals` - списък на терминалите
- `GET /__tb/api/csrf` - получаване на CSRF токен за WebSocket
- `GET /__tb/api/config` - получаване на конфигурация (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` - създаване на нова сесия tmux
- `GET /__tb/app/*` - резервен маршрут на SPA
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` - поточно предаване на входно-изходните операции на терминала

Когато режимът на прокси е активиран:
- `GET /` - пренасочва към проксираното приложение (или `/__tb/app`, ако е изключено)
- `* /*` - препраща към целевото приложение

## Протокол WebSocket

Клиент -> сървър:

```json
{ "type": "input", "data": "ls -la" }
{ "type": "resize", "cols": 120, "rows": 32 }
{ "type": "control", "key": "ctrl_c" }
```

Сървър -> клиент:

```json
{ "type": "output", "data": "..." }
{ "type": "status", "state": "connected" }
```

## Стек UI

- Vite + TanStack Router
- xterm.js + добавката Fit + рендериране чрез WebGL
- Подредба за мобилни устройства с фиксирана лента за въвеждане
- Автоматично повторно свързване с експоненциално увеличаване на интервала (до 10 опита)
- Индикатор за състоянието на връзката