# Architektúra

## Magas szintű folyamat

Alapértelmezett mód (helyi tmux + alagút):

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

Közvetlen sandbox mód (Daytona, alagút nélkül):

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

Ha be van állítva a `--no-tunnel`, a Termbridge kihagyja a Cloudflare-t, és a megadott nyilvános URL-t használja.

## Komponensek

### CLI folyamat

- Elindítja a HTTP szervert, amely kiszolgálja a UI eszközöket.
- Elindítja a terminál I/O-hoz szükséges WebSocket-szervert.
- Létrehoz egy vagy több tmux munkamenetet (vagy Daytona PTY-t).
- Egyszer felhasználható beváltási tokeneket bocsát ki.
- Engedélyezés esetén elindítja és felügyeli az alagutat (jelenleg: Cloudflare).
- Közvetlen sandbox módban elindítja a Termbridge-t a sandboxban, majd megvárja a megosztási URL-t.

### Terminálháttér

- **tmux háttér**: A `node-pty` használatával csatlakozik a tmux-hoz, hogy a valódi billentyűleütéseket és kimenetet kezelje.
- **Daytona háttér**: Sandboxon belüli Daytona PTY-ket használ.
- Beállítja a `TERM=xterm-256color` és a `COLORTERM=truecolor` értékét a teljes színtámogatáshoz.
- tmux esetén letiltja a tmux állapotsorát, hogy a UI tiszta maradjon.

### Terminál-nyilvántartás

- Nyomon követi az elérhető terminál-munkameneteket.
- Listát biztosít a UI számára, és ellenőrzi a kiválasztott terminálazonosítókat.

### Hitelesítés és munkamenet

- Az egyszer használatos token URL formájában jelenik meg, és QR kóddá van kódolva.
- A `GET /__tb/s/:token` beváltja a tokent, és cookie-alapú munkamenetet állít be.
- A WebSocket-kapcsolatokhoz érvényes munkamenet-cookie és CSRF-token szükséges.
- A CSRF-token lekérése a `GET /__tb/api/csrf` használatával történik, és WebSocket-lekérdezési paraméterként kerül továbbításra.

### Proxy mód

A `--proxy <port>` megadásakor:
- Minden termbridge-útvonal a `/__tb/` előtag alatt érhető el
- A nem `/__tb/` kérések a célalkalmazáshoz kerülnek továbbításra
- A UI a Terminal/Preview nézeteket jeleníti meg a Nézetváltóban
- A Preview nézet a `/` címre mutató iframe-et tölt be
- A HMR-hez tartozó WebSocket-kapcsolatok továbbítódnak a célhoz

### Biztonság

- **CSRF-védelem**: A WebSocket-frissítésekhez CSRF-token szükséges a webhelyek közötti eltérítés megakadályozásához.
- **Bemeneti korlátok**: 64KB-os HTTP törzs, 1MB-os WebSocket-üzenet, üzenetenként 64KB terminálbemenet.
- **Sebességkorlátozás**: Tokenbeváltási és WebSocket-kapcsolati korlátok IP szerint.

## API végpontok

Az összes útvonal a `/__tb/` előtag alatt érhető el, hogy ne ütközzön a proxyn továbbított alkalmazásokkal:

- `GET /__tb/healthz` – állapotellenőrzés
- `GET /__tb/s/:token` – token beváltása → cookie → átirányítás
- `GET /__tb/api/terminals` – terminálok listázása
- `GET /__tb/api/csrf` – CSRF-token lekérése WebSockethez
- `GET /__tb/api/config` – konfiguráció lekérése (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` – új tmux munkamenet létrehozása
- `GET /__tb/app/*` – SPA tartalékútvonal
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` – terminál I/O-adatfolyam

Proxy mód engedélyezésekor:
- `GET /` – átirányítás a proxyn elérhető alkalmazáshoz (vagy `/__tb/app`-hez, ha le van tiltva)
- `* /*` – továbbítás a célalkalmazáshoz

## WebSocket-protokoll

Kliens -> szerver:

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

Szerver -> kliens:

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

## UI-verem

- Vite + TanStack Router
- xterm.js + Fit-kiegészítő + WebGL-megjelenítő
- Elsősorban mobilra szabott elrendezés rögzített beviteli sávval
- Automatikus újracsatlakozás exponenciális várakozással (legfeljebb 10 próbálkozás)
- Kapcsolatállapot-jelző