# Architektúra

## Vysokoúrovňový tok

Predvolené nastavenie (lokálny tmux + tunel):

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

Priamy režim sandboxu (Daytona, bez tunela):

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

Keď je nastavené `--no-tunnel`, Termbridge preskočí Cloudflare a použije vami zadané verejné URL.

## Komponenty

### Proces CLI

- Spustí server HTTP, ktorý poskytuje zdroje UI.
- Spustí server WebSocket pre vstup a výstup terminálu.
- Vytvorí jednu alebo viac relácií tmux (alebo Daytona PTY).
- Vydá jednorazové tokeny na uplatnenie.
- Spustí a monitoruje tunel, ak je povolený (aktuálne Cloudflare).
- V priamom režime sandboxu spustí Termbridge v sandboxe a čaká na zdieľací URL.

### Backend terminálu

- **Backend tmux**: Používa `node-pty` na pripojenie k tmux pre skutočný vstup z klávesnice a výstup.
- **Backend Daytona**: Používa PTY Daytona v sandboxe.
- Nastaví `TERM=xterm-256color` a `COLORTERM=truecolor` na plnú podporu farieb.
- Pre tmux vypne stavový riadok tmux, aby rozhranie UI zostalo prehľadné.

### Register terminálov

- Sleduje dostupné relácie terminálu.
- Poskytuje zoznam pre UI a overuje vybrané ID terminálov.

### Overovanie a relácia

- Jednorazový token sa vypíše ako URL a zakóduje do kódu QR.
- `GET /__tb/s/:token` uplatní token a nastaví relačnú cookie.
- Pripojenia WebSocket vyžadujú platnú relačnú cookie a token CSRF.
- Token CSRF sa načíta cez `GET /__tb/api/csrf` a odovzdá sa ako parameter dotazu WebSocket.

### Režim proxy

Keď je zadané `--proxy <port>`:
- Všetky trasy termbridge sa nachádzajú pod prefixom `/__tb/`
- Požiadavky, ktoré nie sú `/__tb/`, sa presmerujú na cieľovú aplikáciu
- UI sprístupňuje zobrazenia Terminál/Náhľad cez prepínač zobrazení
- Zobrazenie Náhľad načíta iframe smerujúci na `/`
- Pripojenia WebSocket pre HMR sa presmerujú na cieľ

### Zabezpečenie

- **Ochrana CSRF**: Aktualizácia pripojenia WebSocket vyžaduje token CSRF, aby sa zabránilo únosu z inej stránky.
- **Limity vstupu**: telo HTTP s veľkosťou 64 KB, správa WebSocket s veľkosťou 1 MB, vstup terminálu s veľkosťou 64 KB na správu.
- **Obmedzenie frekvencie**: Limity na uplatnenie tokenov a pripojenia WebSocket pre každé IP.

## Koncové body API

Všetky trasy sa nachádzajú pod prefixom `/__tb/`, aby nedochádzalo ku konfliktom s aplikáciami, na ktoré sa presmerúva:

- `GET /__tb/healthz` – kontrola stavu
- `GET /__tb/s/:token` – uplatnenie tokenu → cookie → presmerovanie
- `GET /__tb/api/terminals` – zoznam terminálov
- `GET /__tb/api/csrf` – získanie tokenu CSRF pre WebSocket
- `GET /__tb/api/config` – získanie konfigurácie (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` – vytvorenie novej relácie tmux
- `GET /__tb/app/*` – záložná trasa SPA
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` – streamovanie vstupu a výstupu terminálu

Keď je povolený režim proxy:
- `GET /` – presmeruje na aplikáciu proxy (alebo `/__tb/app`, ak je vypnutá)
- `* /*` – presmeruje sa na cieľovú aplikáciu

## Protokol WebSocket

Klient -> server:

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

Server -> klient:

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

## Zásobník UI

- Vite + TanStack Router
- xterm.js + doplnok Fit + vykresľovač WebGL
- Rozloženie navrhnuté najprv pre mobilné zariadenia s pevným panelom vstupu
- Automatické opätovné pripojenie s exponenciálnym predlžovaním intervalov (najviac 10 pokusov)
- Indikátor stavu pripojenia