# Arhitectură

## Fluxul general

Implicit (local tmux + tunel):

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

Mod sandbox direct (Daytona, fără tunel):

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

Când este setat `--no-tunnel`, Termbridge omite Cloudflare și folosește URL public furnizat de dumneavoastră.

## Componente

### Procesul CLI

- Pornește serverul HTTP care servește resursele UI.
- Pornește serverul WebSocket pentru I/O-ul terminalului.
- Creează una sau mai multe sesiuni tmux (sau PTY-uri Daytona).
- Emite tokenuri de revendicare cu o singură utilizare.
- Pornește și monitorizează tunelul când este activat (Cloudflare în prezent).
- În modul sandbox direct, lansează Termbridge în sandbox și așteaptă linkul de partajare URL.

### Backendul terminalului

- **Backend tmux**: Folosește `node-pty` pentru a se conecta la tmux și a transmite apăsările de taste și ieșirea în timp real.
- **Backend Daytona**: Folosește PTY-uri Daytona în interiorul unui sandbox.
- Setează `TERM=xterm-256color` și `COLORTERM=truecolor` pentru suport complet al culorilor.
- Pentru tmux, dezactivează bara de stare tmux pentru a păstra curat UI.

### Registrul terminalelor

- Urmărește sesiunile de terminal disponibile.
- Oferă o listă pentru UI și validează ID-urile terminalelor selectate.

### Autentificare și sesiune

- Tokenul cu o singură utilizare este afișat ca URL și codificat într-un cod QR.
- `GET /__tb/s/:token` revendică tokenul și setează o sesiune prin cookie.
- Conexiunile WebSocket necesită un cookie de sesiune valid și un token CSRF.
- Tokenul CSRF este preluat prin `GET /__tb/api/csrf` și transmis ca parametru în interogarea WebSocket.

### Modul proxy

Când se transmite `--proxy <port>`:
- Toate rutele termbridge se află sub prefixul `/__tb/`
- Cererile care nu sunt `/__tb/` sunt direcționate prin proxy către aplicația țintă
- UI afișează vizualizările Terminal/Preview prin comutatorul Views
- Vizualizarea Preview încarcă un iframe care indică spre `/`
- Conexiunile WebSocket pentru HMR sunt redirecționate către țintă

### Securitate

- **Protecție CSRF**: upgrade-urile WebSocket necesită un token CSRF pentru a preveni deturnarea între site-uri.
- **Limite de intrare**: corp HTTP de 64KB, mesaj WebSocket de 1MB, intrare în terminal de 64KB per mesaj.
- **Limitarea ratei**: limite per IP pentru revendicarea tokenurilor și conexiunile WebSocket.

## Endpointuri API

Toate rutele se află sub prefixul `/__tb/` pentru a evita conflictele cu aplicațiile direcționate prin proxy:

- `GET /__tb/healthz` - verificare a stării
- `GET /__tb/s/:token` - revendicare token → cookie → redirecționare
- `GET /__tb/api/terminals` - listare terminale
- `GET /__tb/api/csrf` - obținere token CSRF pentru WebSocket
- `GET /__tb/api/config` - obținere configurație (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` - creare sesiune nouă tmux
- `GET /__tb/app/*` - fallback SPA
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` - transmitere I/O terminal

Când modul proxy este activat:
- `GET /` - redirecționează către aplicația prin proxy (sau `/__tb/app` dacă este dezactivat)
- `* /*` - direcționat prin proxy către aplicația țintă

## Protocol WebSocket

Client -> server:

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

Server -> client:

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

## Stiva UI

- Vite + TanStack Router
- xterm.js + extensia Fit + randare WebGL
- Interfață concepută pentru mobil, cu bară de introducere fixă
- Reconectare automată cu pauze exponențiale (până la 10 încercări)
- Indicator al stării conexiunii