# Arkitektur

## Övergripande flöde

Standard (lokal tmux + tunnel):

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

Direkt sandboxläge (Daytona, ingen tunnel):

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

När `--no-tunnel` är inställd hoppar Termbridge över Cloudflare och använder den offentliga URL du har angett.

## Komponenter

### CLI-processen

- Startar HTTP-servern som levererar UI-resurserna.
- Startar WebSocket-servern för terminalens in- och utdata.
- Skapar en eller flera tmux-sessioner (eller Daytona-PTY:er).
- Utfärdar engångskoder för inlösen.
- Startar och övervakar tunneln när den är aktiverad (Cloudflare i dag).
- I direkt sandboxläge startas Termbridge i sandlådan, och processen väntar på delnings-URL.

### Terminalbackend

- **tmux-backend**: Använder `node-pty` för att ansluta till tmux för riktiga tangenttryckningar och utdata.
- **Daytona-backend**: Använder Daytona-PTY:er i en sandlåda.
- Ställer in `TERM=xterm-256color` och `COLORTERM=truecolor` för fullt färgstöd.
- För tmux inaktiveras statusfältet tmux så att UI hålls ren.

### Terminalregister

- Håller reda på tillgängliga terminalsessioner.
- Tillhandahåller en lista för UI och validerar valda terminal-ID:n.

### Autentisering och session

- Engångstoken skrivs ut som en URL och kodas i en QR-kod.
- `GET /__tb/s/:token` löser in tokenen och skapar en cookiebaserad session.
- WebSocket-anslutningar kräver en giltig sessionscookie och CSRF-token.
- CSRF-token hämtas via `GET /__tb/api/csrf` och skickas som en frågeparameter i WebSocket-anslutningen.

### Proxy-läge

När `--proxy <port>` skickas med:
- Ligger alla termbridge-rutter under prefixet `/__tb/`
- Proxyas förfrågningar som inte är `/__tb/` till målappen
- UI visar vyerna Terminal/Preview via vyväljaren
- Preview-vyn läser in en iframe som pekar på `/`
- WebSocket-anslutningar för HMR vidarebefordras till målet

### Säkerhet

- **CSRF-skydd**: WebSocket-uppgraderingar kräver en CSRF-token för att förhindra kapning mellan webbplatser.
- **Indatagränser**: 64 KB HTTP-innehåll, 1 MB per WebSocket-meddelande, 64 KB terminalindata per meddelande.
- **Hastighetsbegränsning**: Gränser per IP för tokeninlösen och WebSocket-anslutningar.

## API-slutpunkter

Alla rutter ligger under prefixet `/__tb/` för att undvika konflikter med proxyade appar:

- `GET /__tb/healthz` – hälsokontroll
- `GET /__tb/s/:token` – tokeninlösen → cookie → omdirigering
- `GET /__tb/api/terminals` – lista terminaler
- `GET /__tb/api/csrf` – hämta CSRF-token för WebSocket
- `GET /__tb/api/config` – hämta konfiguration (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` – skapa en ny tmux-session
- `GET /__tb/app/*` – SPA-reservrutt
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` – strömma terminalens in- och utdata

När proxy-läget är aktiverat:
- `GET /` – omdirigerar till den proxyade appen (eller `/__tb/app` om inaktiverat)
- `* /*` – proxyas till målappen

## WebSocket-protokoll

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" }
```

## UI-stacken

- Vite + TanStack Router
- xterm.js + Fit-tillägg + WebGL-renderare
- Mobilanpassad layout med ett fast inmatningsfält
- Automatisk återanslutning med exponentiell väntetid (upp till 10 försök)
- Indikator för anslutningsstatus