# Arhitektuur

## Üldine töövoog

Vaikimisi (kohalik tmux + tunnel):

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

Otsene liivakastirežiim (Daytona, tunnelita):

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

Kui määratud on `--no-tunnel`, jätab Termbridge vahele Cloudflare ja kasutab teie antud avalikku URL.

## Komponendid

### CLI protsess

- Käivitab HTTP-serveri, mis teenindab UI-varasid.
- Käivitab terminali sisend-/väljundtoimingu jaoks WebSocket-serveri.
- Loob ühe või mitu tmux-seanssi (või Daytona pseudoterminali).
- Väljastab ühekordsed lunastustokenid.
- Käivitab ja jälgib tunneli tööd, kui see on lubatud (praegu Cloudflare).
- Otseses liivakastirežiimis käivitab Termbridge liivakastis ja ootab jagamis-URL-i.

### Terminali taustaprogramm

- **tmux taustaprogramm**: kasutab `node-pty`-i, et ühenduda tmux-ga ja edastada päris klahvivajutusi ning väljundit.
- **Daytona taustaprogramm**: kasutab liivakastis Daytona pseudoterminale.
- Täieliku värvitoe jaoks määrab `TERM=xterm-256color` ja `COLORTERM=truecolor`.
- tmux puhul keelab puhta UI hoidmiseks olekuriba tmux.

### Terminalide register

- Jälgib saadaolevaid terminaliseansse.
- Annab loendi UI-ile ja valideerib valitud terminalide ID-d.

### Autentimine ja seanss

- Ühekordne token prinditakse kujul URL ja kodeeritakse kujule QR.
- `GET /__tb/s/:token` lunastab tokeni ja määrab küpsisega seansi.
- WebSocket-ühenduse jaoks on vaja kehtivat seansiküpsist ja CSRF-tokenit.
- CSRF-token hangitakse `GET /__tb/api/csrf` kaudu ja edastatakse WebSocketi päringuparameetris.

### Puhverserveri režiim

Kui edastatakse `--proxy <port>`:
- Kõik termbridge'i marsruudid asuvad eesliite `/__tb/` all
- Mitte-`/__tb/` päringud edastatakse sihtrakendusele puhverserveri kaudu
- UI avaldab vahetaja Views kaudu Terminali ja eelvaate vaated
- Eelvaate vaade laadib iframe'i, mis osutab aadressile `/`
- HMR-i WebSocket-ühendused suunatakse edasi sihtmärgile

### Turvalisus

- **CSRF-kaitse**: WebSocketi ühenduse loomine nõuab CSRF-tokenit, et vältida saitidevahelist kaaperdamist.
- **Sisendi piirangud**: 64KB HTTP keha, 1MB WebSocketi sõnumi kohta, 64KB terminalisisendi kohta sõnumis.
- **Kiiruse piiramine**: tokeni lunastamisel ja WebSocket-ühendustel on piirangud IP kohta.

## API lõpp-punktid

Kõik marsruudid asuvad eesliite `/__tb/` all, et vältida konflikte puhverserveri kaudu edastatavate rakendustega:

- `GET /__tb/healthz` – seisukorra kontroll
- `GET /__tb/s/:token` – tokeni lunastamine → küpsis → ümbersuunamine
- `GET /__tb/api/terminals` – terminalide loendi pärimine
- `GET /__tb/api/csrf` – WebSocketi CSRF-tokeni pärimine
- `GET /__tb/api/config` – seadistuse pärimine (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` – uue tmux-seansi loomine
- `GET /__tb/app/*` – SPA varutee
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` – terminali sisend-/väljundi voogedastus

Kui puhverserveri režiim on lubatud:
- `GET /` – suunab puhverserveri kaudu edastatud rakendusse (või aadressile `/__tb/app`, kui see on keelatud)
- `* /*` – edastatakse sihtrakendusele puhverserveri kaudu

## WebSocketi 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 tehnoloogiakomplekt

- Vite + TanStack Router
- xterm.js + Fit-lisand + WebGL-renderdaja
- Mobiilseadmetele esmajärjekorras kujundus fikseeritud sisendriba abil
- Automaatne taasühendamine kasvava viitega (kuni 10 katset)
- Ühenduse oleku näidik